# Wan-AI/Wan2.7 Image API This document describes the input and output parameters for calling the `wan2.7-image` and `wan2.7-image-pro` models, for reference when using the API. - Synchronous API: `/v1/images/generations` - Asynchronous API: `/v1/tasks/submit` + `/v1/tasks/status` --- ## Model List | Model Name | Description | | ---------- | ----------- | | `wan2.7-image` | Wan2.7 image generation model | | `wan2.7-image-pro` | Wan2.7 image generation Pro model | ## Capability Overview Wan2.7 currently supports: - Text-to-image generation - Single image editing - Multi-image fusion / multi-image editing - Sequential multi-image generation / image set generation ## OpenAI-Compatible API (Synchronous) ### Endpoint `POST https://api-us-ca.umodelverse.ai/v1/images/generations` ### Authentication `Authorization: Bearer $MODELVERSE_API_KEY` ### Request Parameters | Field | Type | Required | Default | Description | | ----- | ---- | -------- | ------- | ----------- | | model | string | Yes | - | Model name. Options: `wan2.7-image`, `wan2.7-image-pro` | | prompt | string | Optional | - | Text prompt. At least one of `prompt`, `image`, or `images` must be provided. | | image | string | Optional | - | Single image input (public URL or Base64). Used for single image editing. | | images | array[string] | Optional | - | Multiple image inputs (public URL or Base64). Used for multi-image fusion/editing. If both `images` and `image` are provided, `images` takes priority. | | size | string | Optional | - | Output size. Supports `1K`, `2K`, `4K`, or `1024x1024`, `2048x2048`, `4096x4096`. | | n | int | Optional | 1 | Number of images to generate. Recommended `1~4`. Larger values allowed when `enable_sequential` is enabled. | | seed | int | Optional | - | Random seed. Positive integer recommended. `0` or omitted means unset. | | watermark | boolean | Optional | false | Whether to add watermark. | | thinking_mode | boolean | Optional | false | Whether to enable deep thinking mode. | | enable_sequential | boolean | Optional | false | Whether to enable sequential/image set generation. Recommended to use with `n`. | ### Request Examples #### 1. Text-to-Image ```bash curl --location 'https://api-us-ca.umodelverse.ai/v1/images/generations' \ --header "Authorization: Bearer $MODELVERSE_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "model": "wan2.7-image", "prompt": "A futuristic cloud data center floating above the sea at sunrise", "size": "1K", "seed": 123456, "watermark": false }' ``` #### 2. Single Image Editing ```bash curl --location 'https://api-us-ca.umodelverse.ai/v1/images/generations' \ --header "Authorization: Bearer $MODELVERSE_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "model": "wan2.7-image-pro", "prompt": "Transform this cat into a cyberpunk style with neon lighting and cinematic composition", "image": "https://umodelverse-inference.cn-wlcb.ufileos.com/ucloud-maxcot.jpg", "size": "2K", "thinking_mode": true, "watermark": false }' ``` #### 3. Multi-Image Fusion ```bash curl --location 'https://api-us-ca.umodelverse.ai/v1/images/generations' \ --header "Authorization: Bearer $MODELVERSE_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "model": "wan2.7-image-pro", "prompt": "Combine the main features of two reference images to create a premium brand poster", "images": [ "https://umodelverse-inference.cn-wlcb.ufileos.com/ucloud-maxcot.jpg", "https://umodelverse-inference.cn-wlcb.ufileos.com/ucloud-maxcot.jpg" ], "size": "2048x2048", "thinking_mode": true, "seed": 20260402 }' ``` #### 4. Sequential Multi-Image Generation ```bash curl --location 'https://api-us-ca.umodelverse.ai/v1/images/generations' \ --header "Authorization: Bearer $MODELVERSE_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "model": "wan2.7-image-pro", "prompt": "Generate a series of posters showing the same character across spring, summer, autumn, and winter, maintaining consistent appearance", "size": "2K", "thinking_mode": true, "enable_sequential": true, "n": 4 }' ``` ### Response Parameters | Field | Type | Description | | -------- | ------- | ----------------------------------------------------- | | created | integer | Unix timestamp (seconds) when the request was created | | data | array | List of generated images | | data.url | string | URL to download the generated image | ### Response Example ```json { "created": 1775558400, "data": [ { "url": "https://example.com/generated-image-1.png" }, { "url": "https://example.com/generated-image-2.png" } ] } ``` ## Asynchronous Task API ### Submit Task #### Endpoint `POST https://api-us-ca.umodelverse.ai/v1/tasks/submit` #### Authentication `Authorization: Bearer $MODELVERSE_API_KEY` #### Request Body ```json { "model": "wan2.7-image-pro", "input": { "prompt": "A ragdoll cat sitting by a café window", "images": [ "https://umodelverse-inference.cn-wlcb.ufileos.com/ucloud-maxcot.jpg" ] }, "parameters": { "size": "2K", "prompt_extend": true, "enable_sequential": true, "n": 4, "seed": 123456, "watermark": false } } ``` #### Request Parameters | Field | Type | Required | Description | | ---------------------------- | ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | model | string | Yes | Model name. Options: `wan2.7-image`, `wan2.7-image-pro` | | input.prompt | string | Optional | Text prompt. At least one of `input.prompt`, `input.images`, `input.img_url`, or `input.first_frame_url` must be provided. | | input.images | array[string] | Optional | Multiple image inputs (URL or Base64). Takes priority if multiple image fields are provided. | | input.img_url | string | Optional | Single image input (URL or Base64). Used for single image editing. | | input.first_frame_url | string | Optional | Compatibility field for single image input. Treated as a normal image in Wan2.7 tasks. | | parameters.size | string | Optional | Output size. Supports `1K`, `2K`, `4K`, or equivalent resolutions. | | parameters.n | int | Optional | Number of images to generate (`1~4`). | | parameters.seed | int | Optional | Random seed. Positive integer recommended. | | parameters.watermark | boolean | Optional | Whether to add watermark. | | parameters.enable_sequential | boolean | Optional | Enable sequential/image set generation. | | parameters.prompt_extend | boolean | Optional | Prompt enhancement. When `true`, maps to `thinking_mode=true` in Wan2.7. | #### Request Examples ##### 1. Text-to-Image ```bash curl --location 'https://api-us-ca.umodelverse.ai/v1/tasks/submit' \ --header "Authorization: Bearer $MODELVERSE_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "model": "wan2.7-image", "input": { "prompt": "A futuristic cloud data center floating above the sea at sunrise" }, "parameters": { "size": "1K", "seed": 123456 } }' ``` ##### 2. Single Image Editing ```bash curl --location 'https://api-us-ca.umodelverse.ai/v1/tasks/submit' \ --header "Authorization: Bearer $MODELVERSE_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "model": "wan2.7-image-pro", "input": { "prompt": "Transform this cat into a cyberpunk style with neon lighting and cinematic composition", "img_url": "https://umodelverse-inference.cn-wlcb.ufileos.com/ucloud-maxcot.jpg" }, "parameters": { "size": "2K", "prompt_extend": true, "watermark": false } }' ``` ##### 3. Multi-Image Fusion ```bash curl --location 'https://api-us-ca.umodelverse.ai/v1/tasks/submit' \ --header "Authorization: Bearer $MODELVERSE_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "model": "wan2.7-image-pro", "input": { "prompt": "Combine the main features of two reference images to create a premium brand poster", "images": [ "https://umodelverse-inference.cn-wlcb.ufileos.com/ucloud-maxcot.jpg", "https://umodelverse-inference.cn-wlcb.ufileos.com/ucloud-maxcot.jpg" ] }, "parameters": { "size": "2048x2048", "prompt_extend": true, "seed": 20260402 } }' ``` ##### 4. Sequential Multi-Image Generation ```bash curl --location 'https://api-us-ca.umodelverse.ai/v1/tasks/submit' \ --header "Authorization: Bearer $MODELVERSE_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "model": "wan2.7-image-pro", "input": { "prompt": "Generate a series of posters showing the same character across four seasons, maintaining consistency" }, "parameters": { "size": "2K", "prompt_extend": true, "enable_sequential": true, "n": 4 } }' ``` #### Submission Response Parameters | Field | Type | Description | | -------------- | ------ | ------------------------- | | output.task_id | string | Unique task identifier | | request_id | string | Unique request identifier | #### Submission Response Example ```json { "output": { "task_id": "3c7d6b6c-7cdb-4f37-bf41-7f2b0f1a9f0d" }, "request_id": "req_202604021530000001" } ``` ### Query Task Status #### Endpoint `GET https://api-us-ca.umodelverse.ai/v1/tasks/status?task_id=` #### Request Example ```bash curl --location 'https://api-us-ca.umodelverse.ai/v1/tasks/status?task_id=' \ --header "Authorization: Bearer $MODELVERSE_API_KEY" ``` #### Response Parameters | Field | Type | Description | | ----------------------- | ------------- | -------------------------------------------------------------------- | | output.task_id | string | Task ID | | output.task_status | string | Task status: `Pending`, `Running`, `Success`, `Failure`, `Cancelled` | | output.urls | array[string] | List of generated image URLs | | output.submit_time | integer | Submission timestamp | | output.finish_time | integer | Completion timestamp | | output.error_message | string | Error message if failed | | usage.completion_tokens | integer | Optional, output tokens | | usage.total_tokens | integer | Optional, total tokens | | request_id | string | Request identifier | #### Response Example (Success) ```json { "output": { "task_id": "3c7d6b6c-7cdb-4f37-bf41-7f2b0f1a9f0d", "task_status": "Success", "urls": [ "https://example.com/generated-image-1.png", "https://example.com/generated-image-2.png", "https://example.com/generated-image-3.png", "https://example.com/generated-image-4.png" ], "submit_time": 1775115000, "finish_time": 1775115038 }, "usage": { "completion_tokens": 4, "total_tokens": 4 }, "request_id": "" } ``` #### Response Example (Failure) ```json { "output": { "task_id": "3c7d6b6c-7cdb-4f37-bf41-7f2b0f1a9f0d", "task_status": "Failure", "submit_time": 1775115000, "finish_time": 1775115012, "error_message": "code=InvalidParameter, message=invalid image url" }, "request_id": "" } ```