Skip to main content
Use POST /image/alt or mynth.image.alt() to generate concise alt text for existing image URLs. Submit 1 to 10 URLs per request. By default the REST endpoint is synchronous — results come back in the same response. Set "sync": false to queue the task and receive a 202 with a task ID instead. This endpoint is for images you already have (including ones not generated by Mynth). For content classification of existing images, use Rate Image Content (POST /image/rate).

​
Pricing

/image/alt costs $0.0004 per image. Only images that successfully receive alt text are charged. The full amount for all submitted URLs is reserved up front. If a URL fails, the unused reserve for that image is released. If your balance cannot cover the full reserve, the request returns 422 INSUFFICIENT_BALANCE.

​
Generate alt text with the SDK

import Mynth from "@mynthio/sdk";

const mynth = new Mynth();

const result = await mynth.image.alt({
  urls: ["https://example.com/photo.webp"],
});

console.log(result.getAltTexts());
// [{ status: "success", url: "...", alt: "A ceramic mug on a wooden table." }]
getAltTexts() returns only successful items. Use getErrors() for failures, or inspect result.results item by item.

​
Local files

Pass files instead of urls when the image is local. The SDK uploads first, then calls /image/alt with the resulting URLs. See Upload input images. 
const result = await mynth.image.alt({
  files: [file], // File, Blob, Buffer, or path — same inputs as upload
});

​
Handle per-image results

Images are processed in parallel. A failure on one URL does not fail the others. The task still completes with a per-URL results array. Success item: 
{
  "status": "success",
  "url": "https://example.com/photo-1.webp",
  "alt": "A ceramic mug on a wooden table beside a window."
}
Failure item: 
{
  "status": "failed",
  "url": "https://example.com/photo-2.webp",
  "error": { "code": "FETCH_FAILED" }
}
CodeMeaning
FETCH_FAILEDThe image could not be downloaded from the URL.
ALT_GENERATION_FAILEDThe image was fetched but alt text generation failed.
UNKNOWN_ERRORAn unexpected error. Retry if it persists.
for (const item of result.results) {
  if (item.status === "failed") {
    console.error(item.url, item.error.code);
  } else {
    console.log(item.url, item.alt);
  }
}
Only successful items are charged, so task.cost reflects successful URLs only.

​
Constraints

ConstraintLimit
URLs per request1 to 10
Alt text length1 to 160 characters
Alt text describes visible content only. The model is prompted for concise, objective labels (typically under ~100 characters); the API allows up to 160.

​
Generate alt text with REST

curl https://api.mynth.io/image/alt \
  -X POST \
  -H "Authorization: Bearer $MYNTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com/photo-1.webp",
      "https://example.com/photo-2.webp"
    ]
  }'
sync defaults to true. Completed response: 
{
  "data": {
    "task": {
      "id": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP",
      "status": "completed",
      "cost": "0.00080000"
    },
    "results": [
      {
        "status": "success",
        "url": "https://example.com/photo-1.webp",
        "alt": "A ceramic mug on a wooden table beside a window."
      },
      {
        "status": "success",
        "url": "https://example.com/photo-2.webp",
        "alt": "A red hiking backpack on a rocky mountain trail."
      }
    ]
  }
}
In sync mode, if the task does not finish within the sync timeout the endpoint returns 202 pending. If the task fails entirely, it returns 500. See Image Alt Request for full response shapes.

​
Start now, wait later

Use altAsync() when you want to create the task now and wait later: 
const task = await mynth.image.altAsync({
  urls: ["https://example.com/photo.webp"],
});

console.log(task.id);

const result = await task.wait();
console.log(result.getAltTexts());
For REST, set "sync": false: 
{
  "urls": ["https://example.com/photo.webp"],
  "sync": false
}
The API returns a 202 with a task ID. Poll /tasks/:id/status and /tasks/:id/result, or listen for task.image.alt.completed / task.image.alt.failed webhooks. See Async and polling and Use webhooks.

​
How alt text fits

  1. You submit image URLs (or upload files via the SDK).
  2. Mynth fetches each image and generates short alt text with a vision model.
  3. Each URL gets status: "success" and alt, or status: "failed" and error.
  4. Billing charges only successful items; reserved balance for failures is released.
Results preserve request order. Full request and response fields live in Image Alt Request.