Skip to main content
Endpoint: 
POST https://api.mynth.io/image/alt
Authentication: API key or OAuth access token required. Public Access Tokens are not accepted. By default the endpoint is synchronous - results are returned in the response body as a 200. Set "sync": false to queue the task and receive a 202 with a task ID for polling instead. In sync mode, if the task does not finish within the sync timeout the endpoint returns a 202 pending response, and if the task fails it returns a 500.

​
Request body

{
  "urls": ["https://example.com/photo-1.webp", "https://example.com/photo-2.webp"],
  "sync": true
}

​
Fields

FieldTypeDefaultNotes
urlsarrayrequiredImage URLs to generate alt text for. Minimum 1, maximum 10.
syncbooleantrueWhen true, wait for results and return them inline. When false, return a 202 pending task.

​
Response body

​
200 - completed

Returned when sync is true (the default) and the task finishes within the sync timeout. 
{
  "data": {
    "task": {
      "id": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP",
      "status": "completed",
      "cost": "0.00040000"
    },
    "results": [
      {
        "status": "success",
        "url": "https://example.com/photo-1.webp",
        "alt": "A ceramic mug on a wooden table beside a window."
      },
      {
        "status": "failed",
        "url": "https://example.com/photo-2.webp",
        "error": { "code": "ALT_GENERATION_FAILED" }
      }
    ]
  }
}
FieldTypeNotes
data.taskobjectTask record created for this request.
data.resultsarrayOne entry per submitted URL, in the same order. Each entry is a success or failure item.

​
202 - pending

Returned when sync is false, or when sync is true but the task did not finish within the sync timeout. Use the task id to poll for completion. 
{
  "data": {
    "task": {
      "id": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP",
      "status": "pending"
    }
  }
}

​
Success item

{
  "status": "success",
  "url": "https://example.com/photo-1.webp",
  "alt": "A ceramic mug on a wooden table beside a window."
}
FieldTypeNotes
statusstringAlways success.
urlstringThe submitted image URL.
altstringGenerated alt text.

​
Failure item

{
  "status": "failed",
  "url": "https://example.com/photo-2.webp",
  "error": { "code": "ALT_GENERATION_FAILED" }
}
A failure item means that one image could not receive alt text. Other images in the same request are unaffected.
CodeCause
FETCH_FAILEDThe image could not be downloaded from the provided URL.
ALT_GENERATION_FAILEDThe image was downloaded but alt text generation failed.
UNKNOWN_ERRORAn unexpected error occurred. Should not normally occur; treat as a bug and retry.

​
Limits

ConstraintValue
URLs per request1-10
Alt text length1-160 chars

​
Pricing

Each URL is priced at **0.0004∗∗.Thefullamount(‘urls‘x0.0004**. The full amount (`urls` x 0.0004) is reserved from your account balance before processing begins. You are charged only for URLs that successfully receive alt text - the reserved balance for any failed items is released. If your balance is insufficient to reserve the full amount, the request returns 422 INSUFFICIENT_BALANCE.

​
Error responses

StatusBodyCause
400{ success: false, errors: [...] }Request body fails schema validation.
401{ code: "UNAUTHORIZED", ... }Missing or invalid API key or OAuth access token.
422{ code: "INSUFFICIENT_BALANCE" }Account balance is too low to reserve the full cost.
500{ code: "UNKNOWN_ERROR" }sync is true and the alt text task failed. Use async mode or retry to poll the task.
See Errors and Limits for the full error reference.