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

# Batch Generate API: Submit Multiple Asynchronous Tasks

> Submit 1 to 50 asynchronous tasks for one model in a single request, with request-level and item-level idempotency.

Use the Batch Generate API to submit 1 to 50 asynchronous tasks for the same public model. Each item uses the model's normal `input` fields.

Use [Batch Status](/docs/api-reference/batch-status) to retrieve the whole batch, or [Batch Webhooks](/docs/api-reference/batch-webhooks) to receive terminal notifications for every accepted item.

## Before you start

* Create an API key and verify that the target model works with the single-task API.
* Create one stable `Idempotency-Key` for the business operation represented by the whole batch.
* Create a stable, unique `client_item_id` and `idempotency_key` for every item.
* If you plan to receive callbacks, first set up [Batch Webhooks](/docs/api-reference/batch-webhooks).

## Endpoint

```http theme={null}
POST https://api.apixo.ai/api/v1/generateTask/{model}/batches
```

Replace `{model}` with a public model ID, such as `seedream-4-5`.

## Headers

<ParamField header="Authorization" type="string" required>
  API authentication. Format: `Bearer YOUR_API_KEY`.
</ParamField>

<ParamField header="Idempotency-Key" type="string" required>
  Unique idempotency key for the entire batch operation. Reuse the same value when retrying after a timeout or network error.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Request body

<ParamField body="items" type="array" required>
  The task list. It must contain 1 to 50 items.

  <Expandable title="Item fields">
    <ParamField body="items[].client_item_id" type="string" required>
      Your item locator, such as an order ID. It must be unique within this batch and is returned by batch status and webhook payloads.
    </ParamField>

    <ParamField body="items[].idempotency_key" type="string" required>
      Account-level idempotency key for this individual task. Keep it unchanged when retrying the same business item.
    </ParamField>

    <ParamField body="items[].input" type="object" required>
      The normal model input. Refer to the relevant model page for supported modes, fields, and limits.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="webhook_url" type="string">
  Optional public HTTPS endpoint for terminal item notifications. When configured, every accepted item receives one webhook after it succeeds or fails.
</ParamField>

<Warning>
  Batch generation does not use `callback_url`. It is ignored wherever it appears in the batch request, including the root body, an item, or nested `input`. Use only the root-level `webhook_url` for batch notifications.
</Warning>

## Successful submission

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/seedream-4-5/batches" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: batch-20260915-001" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "client_item_id": "order-1001",
        "idempotency_key": "order-1001-v1",
        "input": {
          "mode": "text-to-image",
          "prompt": "An orange cat wearing an astronaut helmet, cinematic lighting",
          "aspect_ratio": "1:1"
        }
      },
      {
        "client_item_id": "order-1002",
        "idempotency_key": "order-1002-v1",
        "input": {
          "mode": "text-to-image",
          "prompt": "A futuristic city floating above a sea of clouds at sunrise",
          "aspect_ratio": "16:9"
        }
      }
    ]
  }'
```

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "batchId": "batch_123",
    "model": "seedream-4-5",
    "status": "queued",
    "replayed": false,
    "newlyAcceptedCount": 2,
    "reusedCount": 0,
    "rejectedCount": 0,
    "items": [
      {
        "ordinal": 0,
        "clientItemId": "order-1001",
        "taskId": "task_123",
        "accepted": true,
        "status": "queued"
      },
      {
        "ordinal": 1,
        "clientItemId": "order-1002",
        "taskId": "task_456",
        "accepted": true,
        "status": "queued"
      }
    ],
    "batchExpiresAt": "2026-10-15T12:00:00"
  }
}
```

### Successful submission response fields

| Field                       | Type           | Description                                                                                                                                    |
| --------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`                      | integer        | API result code. `200` means the batch endpoint processed the request; inspect `items[].accepted` to determine whether each item was accepted. |
| `message`                   | string         | API result message. `success` is returned for a successful submission request.                                                                 |
| `data.batchId`              | string         | Unique batch ID. Use it with the Batch Status API.                                                                                             |
| `data.model`                | string         | Public model ID used for this batch.                                                                                                           |
| `data.status`               | string         | Current batch state, such as `queued`, `running`, or `completed`.                                                                              |
| `data.replayed`             | boolean        | Whether this response replays an existing batch created with the same `Idempotency-Key`.                                                       |
| `data.newlyAcceptedCount`   | integer        | Number of newly accepted items. Reused existing tasks are excluded.                                                                            |
| `data.reusedCount`          | integer        | Number of items that reused an existing task through `idempotency_key`.                                                                        |
| `data.rejectedCount`        | integer        | Number of items that were not accepted and therefore have no executable `taskId`.                                                              |
| `data.items`                | array          | Every item in the batch, in the same order as the request.                                                                                     |
| `data.items[].ordinal`      | integer        | Zero-based item position. Use it only for display or diagnostics, not business association.                                                    |
| `data.items[].clientItemId` | string         | Your item locator. Use it to associate the API task with your own order or job.                                                                |
| `data.items[].taskId`       | string \| null | Platform task ID for an accepted item. It is `null` when the item is not accepted.                                                             |
| `data.items[].accepted`     | boolean        | Whether the item entered the execution flow.                                                                                                   |
| `data.items[].status`       | string         | Current public item state: `queued`, `running`, `succeeded`, `failed`, or `rejected`.                                                          |
| `data.batchExpiresAt`       | string         | Batch record expiration time. Save any business association and results you need before expiration.                                            |

Save `batchId` for batch-level lookup, `taskId` for individual task lookup, and `clientItemId` for your business association.

## Item rejection in an otherwise valid batch

The request itself can return successfully while an individual item is not accepted. For example, an item with invalid model input is marked `rejected`:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "batchId": "batch_124",
    "status": "queued",
    "newlyAcceptedCount": 1,
    "reusedCount": 0,
    "rejectedCount": 1,
    "items": [
      {
        "ordinal": 0,
        "clientItemId": "order-1003",
        "taskId": "task_789",
        "accepted": true,
        "status": "queued"
      },
      {
        "ordinal": 1,
        "clientItemId": "order-1004",
        "taskId": null,
        "accepted": false,
        "status": "rejected",
        "error": {
          "code": "INVALID_PARAM_VALUE",
          "message": "The model input is invalid"
        }
      }
    ]
  }
}
```

| Field                        | Type    | Description                                                                |
| ---------------------------- | ------- | -------------------------------------------------------------------------- |
| `data.items[].accepted`      | boolean | `false` means this item did not enter the execution flow.                  |
| `data.items[].status`        | string  | `rejected` means the item was rejected during submission.                  |
| `data.items[].taskId`        | null    | A rejected item has no task ID and cannot be queried or receive a webhook. |
| `data.items[].error.code`    | string  | Programmatic rejection reason.                                             |
| `data.items[].error.message` | string  | Developer-facing explanation of the rejection.                             |

Continue only with `accepted: true` items. Correct rejected input, then submit the corrected work as a new business operation with new batch and item idempotency keys.

## Whole-request failure

The entire request fails and no executable batch is created when, for example:

* `Idempotency-Key` is missing.
* `items` is empty or contains more than 50 items.
* `client_item_id` or `idempotency_key` is duplicated within one batch.
* The JSON body exceeds 5 MiB.
* `webhook_url` is not a public HTTPS address.

```json theme={null}
{
  "code": 400,
  "message": "client_item_id and idempotency_key must be present and unique in one batch",
  "data": null
}
```

| Field     | Type    | Description                                                        |
| --------- | ------- | ------------------------------------------------------------------ |
| `code`    | integer | HTTP or business error code. This is not an accepted batch result. |
| `message` | string  | Reason why the whole batch request failed.                         |
| `data`    | null    | No batch or item list is created after envelope validation fails.  |

## Idempotent retry

If a timeout or network interruption prevents you from knowing whether the response arrived:

1. Retry the whole request with the **same** `Idempotency-Key`.
2. Keep the **same** `idempotency_key` for every original item.
3. APIXO replays the existing batch. `replayed: true` indicates a safe batch replay.

<Tip>
  An idempotency key represents one business operation. Do not change it merely because an HTTP request timed out, or a new batch or task may be created.
</Tip>

## Next steps

* Read [Batch Status](/docs/api-reference/batch-status) to query the whole batch. Use the Single Tasks > Status Task page to query one `taskId`.
* Read [Batch Webhooks](/docs/api-reference/batch-webhooks) to receive a terminal notification for each item.