ImgSEO API Documentation

The ImgSEO API allows you to automatically generate SEO-optimized alt text for images, verify your account credits, and check the API status.

Base URL:

https://api.imgseo.net

1. Health Check

Verify if the API is up and running.

Request:

GET /health

Response:

{
  "status": "API operativa"
}

2. Check Remaining Credits

Retrieve your available credits and account status.

Request:

GET /credits

Headers:

imgseo-token: <your-token>

Response:

{
  "credits_remaining": 1010,
  "user_id": "user-id",
  "status": "active"
}

3. Generate Alt Text

Generate descriptive, SEO-friendly alt text for any image.

Request:

POST /genera-alt-text

Headers:

Content-Type: application/json
imgseo-token: <your-token>

Body Parameters:

Field	Type	Required	Default	Description
`image_url`	string	✅	–	Publicly accessible image URL
`prompt`	string	optional	–	Custom prompt to guide the description
`lang`	string	optional	`it`	Language of the generated alt text (e.g., `en`, `it`, `es`)
`optimize`	boolean	optional	`true`	If `true`, optimizes the image before processing to save AI tokens
`image_name`	string	optional	–	Optional custom file name

Example Request Body:

{
  "image_url": "https://example.com/image.jpg",
  "prompt": "Describe this image",
  "lang": "en",
  "optimize": true,
  "image_name": "desert-landscape.jpg"
}

Response:

{
  "alt_text": "Two people watching a desert landscape at sunset",
  "model": "usedmodel",
  "credits_remaining": 67,
  "image_optimized": true,
  "file_name": "desert-landscape.jpg"
}

Code Examples

cURL

# Check credits
curl -X GET https://api.imgseo.net/credits \
  -H 'imgseo-token: your-token'

# Generate alt text
curl -X POST https://api.imgseo.net/genera-alt-text \
  -H 'Content-Type: application/json' \
  -H 'imgseo-token: your-token' \
  -d '{"image_url":"https://example.com/image.jpg"}'

JavaScript

// Check credits
fetch('https://api.imgseo.net/credits', {
  headers: {'imgseo-token': 'your-token'}
})
.then(res => res.json())
.then(data => console.log(data.credits_remaining));

// Generate alt text
fetch('https://api.imgseo.net/genera-alt-text', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'imgseo-token': 'your-token'
  },
  body: JSON.stringify({
    image_url: 'https://example.com/image.jpg'
  })
})
.then(res => res.json())
.then(data => console.log(data.alt_text));

PHP

// Check credits
$ch = curl_init('https://api.imgseo.net/credits');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['imgseo-token: your-token']);
$credits = json_decode(curl_exec($ch), true)['credits_remaining'];

// Generate alt text
$ch = curl_init('https://api.imgseo.net/genera-alt-text');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'imgseo-token: your-token'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'image_url' => 'https://example.com/image.jpg'
]));
$alt_text = json_decode(curl_exec($ch), true)['alt_text'];

Error Codes

Code	Meaning
400	Missing parameters
401	Authentication failed
402	Not enough credits
403	Invalid token
500	Internal server error

Notes

Each request to /genera-alt-text consumes 1 credit.
The optimize flag reduces image size to minimize AI token consumption.
The default AI model is optimized for the best quality/cost ratio.

Vuoi che ti prepari anche una versione markdown ben formattata con indice (TOC) pronta per GitHub/ReadTheDocs?