> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mynth.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Alt Request

> Reference for the request body and response shape of POST /image/alt.

Endpoint:

```text theme={"theme":"kanagawa-dragon"}
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

```json theme={"theme":"kanagawa-dragon"}
{
  "urls": ["https://example.com/photo-1.webp", "https://example.com/photo-2.webp"],
  "sync": true
}
```

## Fields

| Field  | Type      | Default    | Notes                                                                                            |
| ------ | --------- | ---------- | ------------------------------------------------------------------------------------------------ |
| `urls` | `array`   | *required* | Image URLs to generate alt text for. Minimum `1`, maximum `10`.                                  |
| `sync` | `boolean` | `true`     | When `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.

```json theme={"theme":"kanagawa-dragon"}
{
  "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" }
      }
    ]
  }
}
```

| Field          | Type     | Notes                                                                                    |
| -------------- | -------- | ---------------------------------------------------------------------------------------- |
| `data.task`    | `object` | Task record created for this request.                                                    |
| `data.results` | `array`  | One 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.

```json theme={"theme":"kanagawa-dragon"}
{
  "data": {
    "task": {
      "id": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP",
      "status": "pending"
    }
  }
}
```

### Success item

```json theme={"theme":"kanagawa-dragon"}
{
  "status": "success",
  "url": "https://example.com/photo-1.webp",
  "alt": "A ceramic mug on a wooden table beside a window."
}
```

| Field    | Type     | Notes                    |
| -------- | -------- | ------------------------ |
| `status` | `string` | Always `success`.        |
| `url`    | `string` | The submitted image URL. |
| `alt`    | `string` | Generated alt text.      |

### Failure item

```json theme={"theme":"kanagawa-dragon"}
{
  "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.

| Code                    | Cause                                                                              |
| ----------------------- | ---------------------------------------------------------------------------------- |
| `FETCH_FAILED`          | The image could not be downloaded from the provided URL.                           |
| `ALT_GENERATION_FAILED` | The image was downloaded but alt text generation failed.                           |
| `UNKNOWN_ERROR`         | An unexpected error occurred. Should not normally occur; treat as a bug and retry. |

## Limits

| Constraint       | Value       |
| ---------------- | ----------- |
| URLs per request | 1-10        |
| Alt text length  | 1-160 chars |

## Pricing

Each URL is priced at \*\*$0.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

| 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 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](/reference/errors-and-limits) for the full error reference.