Batch Generate API: Submit Multiple Asynchronous Tasks

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 to retrieve the whole batch, or 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.

Endpoint

POST https://api.apixo.ai/api/v1/generateTask/{model}/batches

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

Headers

string

required

API authentication. Format: Bearer YOUR_API_KEY.

string

required

Unique idempotency key for the entire batch operation. Reuse the same value when retrying after a timeout or network error.

string

required

Must be application/json.

Request body

array

required

The task list. It must contain 1 to 50 items.

Show Item fields

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.

string

required

Account-level idempotency key for this individual task. Keep it unchanged when retrying the same business item.

object

required

The normal model input. Refer to the relevant model page for supported modes, fields, and limits.

string

Optional public HTTPS endpoint for terminal item notifications. When configured, every accepted item receives one webhook after it succeeds or fails.

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.

Successful submission

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"
        }
      }
    ]
  }'

{
  "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:

{
  "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.

{
  "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:

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

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.

Next steps

Read Batch Status to query the whole batch. Use the Single Tasks > Status Task page to query one taskId.
Read Batch Webhooks to receive a terminal notification for each item.

​Before you start

​Endpoint

​Headers

​Request body

​Successful submission

​Successful submission response fields

​Item rejection in an otherwise valid batch

​Whole-request failure

​Idempotent retry

​Next steps

Before you start

Endpoint

Headers

Request body

Successful submission

Successful submission response fields

Item rejection in an otherwise valid batch

Whole-request failure

Idempotent retry

Next steps