Image Alt Request - Mynth - Documentation

Endpoint:

POST https://api.mynth.io/image/alt

Authentication: API key or OAuth access token required. Public Access Tokens are not accepted. The endpoint is async only. It creates an image.alt task and returns 201 with a taskId. Poll task endpoints or use webhooks to get the alt text result.

Request body

{
  "url": "https://example.com/photo-1.webp"
}

Fields

Field	Type	Default	Notes
`url`	`string`	required	Image URL to generate alt text for. Must be http(s).

Response body

`201` — task created

{
  "data": {
    "taskId": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP",
    "estimatedCost": "0.0004"
  }
}

Field	Type	Notes
`data.taskId`	`string`	Task ID. Poll `/tasks/:id` or use webhooks for the result.
`data.estimatedCost`	`string`	Estimated cost in USD reserved for this task. Failed tasks are free.

When the task completes, GET /tasks/:id (or the webhook payload) includes:

{
  "result": {
    "url": "https://example.com/photo-1.webp",
    "alt": "A ceramic mug on a wooden table beside a window."
  }
}

Field	Type	Notes
`url`	`string`	The submitted URL.
`alt`	`string`	Generated alt text.

If generation fails, the task status is failed with errors: [{ code, message? }]. Common codes: FETCH_FAILED, ALT_GENERATION_FAILED, UNKNOWN_ERROR. See Task error codes.

Limits

Constraint	Value
URLs per request	1
Alt text length	1 to 160 characters

Pricing

Each request is priced at $0.0004. That amount is reserved from your account balance before processing begins. You are charged only when the task completes successfully — failed tasks release the reserve. If your balance is insufficient, the request returns 422 INSUFFICIENT_BALANCE.

Error responses

Status	Body	Cause
`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 cost.

See Errors and Limits for the full error reference.

​Request body

​Fields

​Response body

​201 — task created

​Limits

​Pricing

​Error responses