> ## 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.

# Wan 2.7 Image

> Alibaba image generation API for omni-image and omni-image-pro workflows

## Overview

Wan 2.7 Image is an Alibaba image model for text-to-image, image editing, and sequential image generation. Use this page when you are ready to call the API after trying the model in the APIXO playground.

| Capability                  | Value                                                                                                        |
| --------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Model ID                    | `wan-2-7-image`                                                                                              |
| Modes                       | `omni-image`, `omni-image-pro`                                                                               |
| Prompt                      | Required, non-empty; supports Chinese/English; max `5000` characters (model-side truncation)                 |
| Input images                | Optional `image_urls`, `1-9` URLs when provided                                                              |
| Image limits (`image_urls`) | `JPEG/JPG/PNG(no alpha)/BMP/WEBP`, width/height `240-8000` px, ratio `1:8-8:1`, file size `<=20MB`           |
| Resolution tiers            | `1k`, `2k`, `4k`                                                                                             |
| 4k availability             | Only when `mode=omni-image-pro`, no `image_urls`, and `enable_sequential=false`                              |
| Output count (`num_images`) | `1-4` when `enable_sequential=false` (default `1`); `1-12` when `enable_sequential=true`                     |
| Interactive edit boxes      | `bbox_list` requires `image_urls`; list length must match image count; each image supports up to `2` boxes   |
| Color palette control       | `color_palette` is available only when `enable_sequential=false`; `3-10` colors; ratio sum must be `100.00%` |

## Endpoint and authentication

Base URL:

```text theme={null}
https://api.apixo.ai/api/v1
```

| Method | Endpoint                                    | Purpose                               |
| ------ | ------------------------------------------- | ------------------------------------- |
| `POST` | `/generateTask/wan-2-7-image`               | Submit a generation task              |
| `GET`  | `/statusTask/wan-2-7-image?taskId={taskId}` | Poll task status and retrieve results |

All requests require your APIXO API key:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Submit requests also require:

```http theme={null}
Content-Type: application/json
```

## Copy-paste async quickstart

This minimal request submits a text-to-image task and returns a `taskId`.

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/wan-2-7-image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "omni-image-pro",
      "prompt": "a cinematic panda walking through snow",
      "resolution": "2k",
      "num_images": 1
    }
  }'
```

Successful response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}
```

Save the `taskId`; you need it to poll for the final result.

## Poll for result

```bash theme={null}
curl -X GET "https://api.apixo.ai/api/v1/statusTask/wan-2-7-image?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Processing response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "processing",
    "createTime": 1767965610929
  }
}
```

Success response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/image.png\"]}",
    "createTime": 1767965610929,
    "completeTime": 1767965652317,
    "costTime": 41388
  }
}
```

Failed response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "InvalidParameter",
    "failMsg": "The parameter is invalid",
    "createTime": 1767965610929,
    "completeTime": 1767965620132
  }
}
```

Parse `resultJson` after `state` becomes `success`:

```javascript theme={null}
const payload = JSON.parse(data.resultJson);
const imageUrls = payload.resultUrls;
```

## Request body

### Text-to-image

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "omni-image-pro",
    "prompt": "a cinematic panda walking through snow",
    "resolution": "4k",
    "num_images": 2,
    "enable_sequential": false,
    "watermark": false,
    "seed": 42
  }
}
```

### Image editing

```json theme={null}
{
  "request_type": "callback",
  "callback_url": "https://your-server.com/webhooks/apixo",
  "input": {
    "mode": "omni-image",
    "image_urls": [
      "https://example.com/base.png",
      "https://example.com/style.png"
    ],
    "prompt": "blend the style naturally and keep lighting consistent",
    "resolution": "2k",
    "num_images": 1,
    "bbox_list": [
      [[120, 180, 360, 420]],
      []
    ]
  }
}
```

## Parameters

<ParamField body="request_type" type="string" required default="async">
  Result delivery mode. Use `async` for polling with `statusTask`, or `callback` for webhook delivery.
</ParamField>

<ParamField body="callback_url" type="string">
  Required when `request_type` is `callback`. Must be a callback URL that can receive the final task payload. See [Webhooks](/api-reference/webhooks).
</ParamField>

<ParamField body="input" type="object" required>
  Wan 2.7 Image input parameters.

  <Expandable title="properties">
    <ParamField body="mode" type="string" required>
      Generation mode. Supported values: `omni-image`, `omni-image-pro`.
    </ParamField>

    <ParamField body="prompt" type="string" required>
      Prompt text. Required for all requests and cannot be empty after trimming. Supports Chinese/English, maximum length is `5000` characters, and excess content is truncated by the model service.
    </ParamField>

    <ParamField body="image_urls" type="string[]">
      Optional image input list. When provided, must contain `1-9` image URLs. Image constraints: formats `JPEG/JPG/PNG` (no alpha), `BMP`, `WEBP`; width/height `240-8000` px; aspect ratio `1:8-8:1`; file size `<=20MB`.
    </ParamField>

    <ParamField body="resolution" type="string" default="2k">
      Output resolution tier. Supported values: `1k`, `2k`, `4k`. `mode=omni-image` does not support `4k`. `4k` is only available when `mode=omni-image-pro`, `image_urls` is empty, and `enable_sequential=false`.
    </ParamField>

    <ParamField body="num_images" type="integer" default="1">
      Requested output count. Accepts integer or numeric string input. Range is `1-4` when `enable_sequential=false`, and `1-12` when `enable_sequential=true`.
    </ParamField>

    <ParamField body="enable_sequential" type="boolean" default="false">
      Sequential/group generation switch. `false` (default) means normal generation. `true` enables sequential generation mode.
    </ParamField>

    <ParamField body="bbox_list" type="array[array[array[integer]]]">
      Optional interactive edit boxes. Requires `image_urls`. Structure is `bbox_list[image_index][box_index] = [x1,y1,x2,y2]`. The outer list length must equal `image_urls` length. Each image supports up to `2` boxes. Each box must contain exactly `4` integers and satisfy `0<=x1<x2` and `0<=y1<y2`. Example: `[[[120,180,360,420]], []]`.
    </ParamField>

    <ParamField body="color_palette" type="array">
      Optional custom color theme. Available only when `enable_sequential=false`. Must contain `3-10` colors. Each color object must include `hex` (`#RRGGBB`) and `ratio` (`xx.xx%`). All ratio values must sum to `100.00%`.
    </ParamField>

    <ParamField body="negative_prompt" type="string">
      Optional negative prompt used to reduce unwanted visual elements.
    </ParamField>

    <ParamField body="watermark" type="boolean" default="false">
      Whether to add watermark. `false` (default) means no watermark. `true` adds a bottom-right watermark with fixed text `AI 生成`.
    </ParamField>

    <ParamField body="thinking_mode" type="boolean" default="true (model-side)">
      Thinking-mode switch. Effective only when `enable_sequential=false` and no input image is provided. When enabled, the model may improve complex prompt understanding, with additional latency.
    </ParamField>

    <ParamField body="seed" type="integer">
      Optional random seed. Supported range: `0-2147483647`. A fixed seed improves reproducibility, but identical seeds do not guarantee identical outputs.
    </ParamField>
  </Expandable>
</ParamField>

## Response format

### Submit task response

`POST /generateTask/wan-2-7-image` returns a task ID when the task is accepted:

<ResponseField name="code" type="integer">
  API status code. `200` means the task was accepted.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message.
</ResponseField>

<ResponseField name="data.taskId" type="string">
  Unique task identifier used with the status endpoint.
</ResponseField>

### Status response fields

<ResponseField name="taskId" type="string">
  Unique task identifier.
</ResponseField>

<ResponseField name="state" type="string">
  Current task state: `pending`, `processing`, `success`, or `failed`.
</ResponseField>

<ResponseField name="resultJson" type="string">
  JSON string containing generated image URLs in `resultUrls`. Present when `state` is `success`.
</ResponseField>

<ResponseField name="failCode" type="string">
  Machine-readable failure code. Present when `state` is `failed`.
</ResponseField>

<ResponseField name="failMsg" type="string">
  Human-readable failure message. Present when `state` is `failed`.
</ResponseField>

<ResponseField name="createTime" type="integer">
  Task creation timestamp in Unix milliseconds.
</ResponseField>

<ResponseField name="completeTime" type="integer">
  Task completion timestamp in Unix milliseconds. Present after completion.
</ResponseField>

<ResponseField name="costTime" type="integer">
  Processing duration in milliseconds. Present after completion when provider timing is available.
</ResponseField>

If at least one image succeeds, the task can still return `success`, and `resultJson.resultUrls` contains only successful outputs.

## Webhook callback mode

Use callback mode when your backend should receive the final result automatically instead of polling.

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/wan-2-7-image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "callback",
    "callback_url": "https://your-server.com/webhooks/apixo",
    "input": {
      "mode": "omni-image-pro",
      "prompt": "a premium product poster with soft studio light",
      "resolution": "2k",
      "num_images": 1
    }
  }'
```

See [Webhooks](/api-reference/webhooks) for delivery requirements and retry behavior.

## Billing

Wan 2.7 Image is billed per generated image.

| Mode             | APIXO price      |
| ---------------- | ---------------- |
| `omni-image`     | `$0.03 / image`  |
| `omni-image-pro` | `$0.075 / image` |

Billing behavior:

```text theme={null}
precharge = requested_num_images * unit_price
final_charge = successful_images * unit_price
refund = precharge - final_charge (if partial failure)
```

For current public pricing, see [Pricing](https://apixo.ai/pricing). If this route is not listed there, backend billing follows `ModelPricing.md`.

## Latency and polling

Wan 2.7 Image tasks are asynchronous. The backend does not provide a fixed public latency SLA; actual latency varies by prompt complexity, requested image count, image input fetch speed, and queue load.

| Workflow                                         | Recommended first poll      | Poll interval |
| ------------------------------------------------ | --------------------------- | ------------- |
| Text-only generation                             | 10s after task creation     | 5s-10s        |
| Image editing / multi-image input                | 10s-15s after task creation | 5s-10s        |
| Sequential generation (`enable_sequential=true`) | 15s after task creation     | 8s-12s        |

<Tip>
  For production workloads, use callback mode to avoid frequent polling.
</Tip>

Rate limits and concurrency can vary by account, API key, and route. If you receive `429`, slow down requests and retry with backoff. For account-level details, see [System APIs](/api-reference/system).

## Errors and troubleshooting

### HTTP errors

| Code  | Meaning                                        | What to do                           |
| ----- | ---------------------------------------------- | ------------------------------------ |
| `400` | Invalid request body, parameter type, or value | Fix the request before retrying      |
| `401` | Missing or invalid API key                     | Check the `Authorization` header     |
| `402` | Insufficient balance or quota                  | Add balance or switch account/key    |
| `403` | Key or route cannot access the model           | Check permissions and route strategy |
| `429` | Rate limit or concurrency limit reached        | Retry with exponential backoff       |
| `500` | Server error                                   | Retry with backoff                   |
| `502` | Third-party model service error                | Retry with backoff                   |
| `504` | Third-party model timeout                      | Retry or use callback mode           |

### Task failure codes

`failCode` is route-dependent and may come from mapped third-party model failures. Common values include:

| Fail code                                                | Meaning                                            | What to do                            |
| -------------------------------------------------------- | -------------------------------------------------- | ------------------------------------- |
| `PromptInvalid`                                          | Prompt is invalid or rejected by the model service | Rewrite the prompt and retry          |
| `MissingParameter` / `BadRequest`                        | Required fields are missing or malformed           | Check required fields and types       |
| `SensitiveContentDetected` / `ProhibitedContentDetected` | Prompt or image input failed safety checks         | Rewrite prompt or change input images |
| `RateLimitExceeded`                                      | Model service or route rate limit was reached      | Retry with backoff                    |
| `Task TimeOut` / `Timeout`                               | Generation did not finish in time                  | Retry or use callback mode            |

### Parameter troubleshooting

* `mode` must be `omni-image` or `omni-image-pro`.
* `prompt` is required and cannot be empty.
* `resolution` supports only `1k`, `2k`, `4k`.
* `4k` is invalid when `mode=omni-image`, when `enable_sequential=true`, or when `image_urls` is provided.
* `num_images` range depends on `enable_sequential`: `1-4` when false, `1-12` when true.
* `image_urls` supports `1-9` image URLs when provided.
* `bbox_list` requires `image_urls`, its length must match `image_urls`, and each image supports at most `2` boxes.
* `color_palette` is available only when `enable_sequential=false`, with `3-10` colors and total ratio `100.00%`.

See [Error Codes](/api-reference/errors) for the full error reference.

## Related links

* [Generation API Overview](/models)
* [Generate Task](/api-reference/generate-task)
* [Status Task](/api-reference/status-task)
* [Webhooks](/api-reference/webhooks)
* [Error Codes](/api-reference/errors)
* [Parameter Specification](/api-reference/parameters)
* [Pricing](https://apixo.ai/pricing)