AI
AI alt text & SEO
POST /v1/ai/seo — generate alt text, captions, descriptions, and titles from an image URL.
Give helloIMG a URL to an already-hosted image and get back SEO metadata — alt text, a caption, a longer description, and a title — written for it. Available on Unlimited and Unlimited + AI.
Request
POST /v1/ai/seo
Terminal
curl -X POST https://api.helloimg.io/v1/ai/seo \
-H "Authorization: Bearer <your API key>" \
-H "Content-Type: application/json" \
-d '{
"url": "https://shop.example.com/images/product.jpg",
"language": "en",
"context": "Outdoor gear webshop"
}'
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
url | string | yes | — | The image to describe. |
language | string | no | en | Output language (e.g. en, de, fr). |
context | string | no | "" | A short description of the site or shop, to steer tone and vocabulary. |
fields | string | no | all four | Which fields to generate: alt, caption, description, title. |
limits | object | no | see below | Character limits per field. |
Default character limits:
| Field | Limit |
|---|---|
alt | 125 |
caption | 150 |
description | 300 |
title | 80 |
Response
{
"alt": "Yellow safety helmet on a white background",
"caption": "Professional safety helmet for construction work",
"description": "A yellow plastic safety helmet meeting the EN 397 standard. Suited to construction sites, factories, and industrial workplaces.",
"title": "Yellow safety helmet — EN 397 certified",
"cached": false,
"model": "...",
"processing_time_ms": 2100,
"tokens": { "input": 243, "output": 150 }
}
If the exact same image, language, context, fields, and limits were
requested recently, cached is true and the result comes back instantly:
{
"alt": "...",
"caption": "...",
"description": "...",
"title": "...",
"cached": true,
"processing_time_ms": 0
}
Errors
| Status | Body | Cause |
|---|---|---|
400 | { "error": "Missing url parameter", "code": 400 } | No url field. |
400 | { "error": "Invalid JSON body", "code": 400 } | Malformed JSON. |
401 | { "error": "invalid api key" } | Missing or malformed Authorization header. Applies to every /v1/* route — one shared check in front of all of them. |
403 | { "error": "ai requires the Unlimited + AI plan", "code": "ai_plan_required" } | Free plan — AI isn't available at all. |
429 | { "error": "monthly AI credit limit reached", "code": "ai_credits_exhausted" } | Unlimited plan, 100 AI credits already used this month. Unlimited + AI has no cap. |
500 | { "error": "...", "code": 500 } | The AI model call failed. |
Batch generation (several images per request) is available in the
underlying AI service and is planned for the public API — for now, call
/v1/ai/seo once per image.