Wan 3.0 Video API Documentation

Overview

Generate Wan 3.0 videos from text, first-frame images, first and last frames, or image, video, and audio references. Query the returned task ID to read its status and result_url.

Primary Endpoint

POST/api/v1/userWan30/start

Generate a video with `wan3.0-video` or `wan3.0-video-prime`. Both models produce identical quality; `wan3.0-video-prime` only trades a higher per-second price for much faster inference (about 2 minutes instead of about 14 minutes for a 720P 15-second clip). The request/response contract is identical — switch by replacing the model name. Reference mode accepts image, video, audio, file, and public web-page media. Each reference video must be 1–15 seconds; all reference videos together must not exceed 15 seconds, and reference-video plus output duration must not exceed 30 seconds. Strict first-frame/first-last-frame media cannot be mixed with reference media. File and link inputs are mutually exclusive. `prompt_extend` controls upstream prompt rewriting and defaults to false; when it stays off, write prompts following the Wan3.0 creator handbook prompt guide. `negative_prompt` is not supported. ### 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: `model`, `input`, `parameters`. - 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 - `400` — Invalid mode, media combination, or generation parameter. - `401` — Unauthorized - Invalid or missing JWT token. - `503` — Provider or Wan3.0 pricing is not configured. ### Related Operations - `GET /api/v1/userWan30/allRecords` — List Wan3.0 video tasks. - `GET /api/v1/userWan30/{_id}` — Get Wan3.0 video task details. - `DELETE /api/v1/userWan30/{_id}` — Delete a Wan3.0 video task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).

Request Parameters

Name	Type	Required	Description
name	string	No	-
model	enum: wan3.0-video \| wan3.0-video-prime	Yes	default: "wan3.0-video"
mode	enum: text-to-video \| first-frame \| first-last-frames \| reference	No	default: "text-to-video"
minor_suspected_skip	boolean	No	Continue after explicitly confirming a suspected-minor warning. Confirmed minor/CSAM content is always blocked.; default: false
input	object	Yes	-
input.prompt	string	No	maxLength: 5000
input.media	array<object>	No	-
input.media[].type	enum: reference_image \| reference_video \| reference_audio \| first_frame \| last_frame \| file \| link	Yes	-
input.media[].url	string	Yes	-
input.media[].duration	number	No	Input media duration in seconds.
parameters	object	Yes	-
parameters.resolution	enum: 480P \| 720P \| 1080P	No	default: "1080P"
parameters.ratio	enum: adaptive \| 16:9 \| 4:3 \| 1:1 \| 3:4 \| 9:16	No	default: "adaptive"
parameters.duration	integer	No	Output duration from 2 to 30 seconds, or -1 for intelligent duration.; default: 5
parameters.audio	boolean	No	default: true
parameters.prompt_extend	boolean	No	Enable upstream prompt rewriting. Off by default; keep it off and follow the creator handbook prompt guide for stable results.; default: false
parameters.seed	integer	No	minimum: 0; maximum: 2147483647
parameters.watermark	boolean	No	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"
        },
        "model": {
          "type": "string",
          "enum": [
            "wan3.0-video",
            "wan3.0-video-prime"
          ],
          "default": "wan3.0-video"
        },
        "mode": {
          "type": "string",
          "enum": [
            "text-to-video",
            "first-frame",
            "first-last-frames",
            "reference"
          ],
          "default": "text-to-video"
        },
        "minor_suspected_skip": {
          "type": "boolean",
          "default": false,
          "description": "Continue after explicitly confirming a suspected-minor warning. Confirmed minor/CSAM content is always blocked."
        },
        "input": {
          "type": "object",
          "properties": {
            "prompt": {
              "type": "string",
              "maxLength": 5000
            },
            "media": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "type",
                  "url"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "reference_image",
                      "reference_video",
                      "reference_audio",
                      "first_frame",
                      "last_frame",
                      "file",
                      "link"
                    ]
                  },
                  "url": {
                    "type": "string"
                  },
                  "duration": {
                    "type": "number",
                    "description": "Input media duration in seconds."
                  }
                }
              }
            }
          }
        },
        "parameters": {
          "type": "object",
          "properties": {
            "resolution": {
              "type": "string",
              "enum": [
                "480P",
                "720P",
                "1080P"
              ],
              "default": "1080P"
            },
            "ratio": {
              "type": "string",
              "enum": [
                "adaptive",
                "16:9",
                "4:3",
                "1:1",
                "3:4",
                "9:16"
              ],
              "default": "adaptive"
            },
            "duration": {
              "type": "integer",
              "description": "Output duration from 2 to 30 seconds, or -1 for intelligent duration.",
              "default": 5
            },
            "audio": {
              "type": "boolean",
              "default": true
            },
            "prompt_extend": {
              "type": "boolean",
              "default": false,
              "description": "Enable upstream prompt rewriting. Off by default; keep it off and follow the creator handbook prompt guide for stable results."
            },
            "seed": {
              "type": "integer",
              "minimum": 0,
              "maximum": 2147483647
            },
            "watermark": {
              "type": "boolean",
              "default": false
            }
          }
        }
      },
      "required": [
        "model",
        "input",
        "parameters"
      ]
    },
    {
      "$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.image_url: string
data.image_urls: array<string>
data.result_url: string
data.video_url: string
data.result_video_url: string
data.cover_url: string
data.result_cover: string
data.hd_video_url: string
data.video_time: number
data.duration_seconds: number
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/userWan30/start" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "wan3.0-video",
  "mode": "reference",
  "input": {
    "prompt": "Create a cinematic scene using the references.",
    "media": [
      {
        "type": "reference_image",
        "url": "https://example.com/reference.png"
      }
    ]
  },
  "parameters": {
    "resolution": "1080P",
    "ratio": "adaptive",
    "duration": 10,
    "audio": true
  }
}'

Get the generated video

Save data._id from the start response. Query that ID until data.current_status is completed, then read data.result_url. If data.current_status is failed, stop polling and read data.failed_code and data.failed_message for the reason. Poll at a modest interval, for example every 10 seconds. Both Wan 3.0 models use this same workflow.

curl -X GET "https://headswap.app/api/v1/userWan30/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "code": 0,
  "data": {
    "_id": "TASK_ID",
    "current_status": "completed",
    "result_url": "https://example.com/generated-video.mp4"
  }
}

Related Endpoints

GET/api/v1/userWan30/{_id}

Get Wan3.0 video task details

POST/api/v1/userWan30/start

Start Wan3.0 all-in-one video generation

GET/api/v1/userWan30/allRecords

List Wan3.0 video tasks

POST/api/v1/userWan30/batchDetail

Batch get Wan3.0 video task details

DELETE/api/v1/userWan30/{_id}

Delete a Wan3.0 video task

Responses

200

Task created; save data._id for status polling. 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.

400

Invalid mode, media combination, or generation parameter

401

Unauthorized - Invalid or missing bearer token

503

Provider or Wan3.0 pricing is not configured