Overview
Generate images with the Wan 2.7 image model using text prompts and configurable output dimensions.
Primary Endpoint
/api/v1/userWan27Image/startCreate an asynchronous Wan 2.7 image task from a text prompt, with optional input images and generation controls defined by the request schema. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `name`, `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userWan27Image/list` — Get task list. - `GET /api/v1/userWan27Image/detail/{id}` — Get task details. - `DELETE /api/v1/userWan27Image/{id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
Request Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | - |
| prompt | string | Yes | Text prompt (max 5000 chars) |
| creation_mode | enum: text-to-image | image-edit | No | Optional compatibility field for history and mode reporting; callers may omit it. The server ignores any supplied value and records `image-edit` when `input_images` contains a valid HTTP(S) image URL, otherwise `text-to-image`. It is not forwarded to the model provider. |
| model | enum: wan2.7-image | wan2.7-image-pro | No | default: "wan2.7-image" |
| input_images | array<string> | No | Input images for editing (0-9 images, max 20MB each) |
| aspect_ratio | enum: 1:1 | 3:2 | 2:3 | 4:3 | 3:4 | 16:9 | 9:16 | 21:9 | No | default: "1:1" |
| bbox_list | array<array<array<integer>>> | No | One list per input image, in the same order as input_images. Use [] for an image with no box. Each image supports up to two boxes; each box is [x1, y1, x2, y2] in absolute pixels of the original image, from top-left to bottom-right. |
| force_generate | boolean | No | - |
| minor_suspected_skip | boolean | No | Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block.; default: false |
| webhook_url | string | No | HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.; maxLength: 2048 |
| webhook_token | string | No | Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.; maxLength: 256 |
Request schema and conditional rules
{
"allOf": [
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"prompt": {
"type": "string",
"description": "Text prompt (max 5000 chars)"
},
"creation_mode": {
"type": "string",
"enum": [
"text-to-image",
"image-edit"
],
"description": "Optional compatibility field for history and mode reporting; callers may omit it. The server ignores any supplied value and records `image-edit` when `input_images` contains a valid HTTP(S) image URL, otherwise `text-to-image`. It is not forwarded to the model provider."
},
"model": {
"type": "string",
"enum": [
"wan2.7-image",
"wan2.7-image-pro"
],
"default": "wan2.7-image"
},
"input_images": {
"type": "array",
"items": {
"type": "string"
},
"description": "Input images for editing (0-9 images, max 20MB each)"
},
"aspect_ratio": {
"type": "string",
"enum": [
"1:1",
"3:2",
"2:3",
"4:3",
"3:4",
"16:9",
"9:16",
"21:9"
],
"default": "1:1"
},
"bbox_list": {
"type": "array",
"description": "One list per input image, in the same order as input_images. Use [] for an image with no box. Each image supports up to two boxes; each box is [x1, y1, x2, y2] in absolute pixels of the original image, from top-left to bottom-right.",
"items": {
"type": "array",
"maxItems": 2,
"items": {
"type": "array",
"minItems": 4,
"maxItems": 4,
"items": {
"type": "integer",
"minimum": 0
}
}
},
"example": [
[],
[
[
989,
515,
1138,
681
]
]
]
},
"force_generate": {
"type": "boolean"
},
"minor_suspected_skip": {
"type": "boolean",
"default": false,
"description": "Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."
}
},
"required": [
"name",
"prompt"
]
},
{
"$ref": "#/components/schemas/WebhookInput"
}
]
}Response Fields
- code: enum: 0
- data: object
- data._id: string
- Task ID for detail and batch polling.
- data.name: string
- data.prompt: string
- data.is_downloaded: boolean
- data.is_previewed: boolean
- data.current_status: string
- Persisted task state; use the concrete task family schema for its allowed values and terminal states.
- data.createdAt: string
- data.updatedAt: string
- data.expirationDate: string
- data.remainingDays: number
- data.isExpired: boolean
- data.coins: number
- data.hasRefundCoin: boolean
- Whether charged credits were refunded.
- data.failed_code: string
- data.failed_message: string
- data.failed_reason: string
- Public failure category when available.
- data.creation_mode: string
- data.image_url: string
- data.image_urls: array<string>
- data.result_image_url: string
- data.result_image_urls: array<string>
- data.input_images: array<string>
- data.nsfw_detected: enum: true
- data.message: string
- trace_id: string
- Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.
Request Example
curl -X POST "https://headswap.app/api/v1/userWan27Image/start" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "My Task",
"prompt": "high quality, clear, cinematic"
}'Related Endpoints
Responses
Task started successfully or NSFW content detected. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.
Unauthorized - Invalid or missing bearer token