Quick start
Create a key in your Comfy workspace and export it asCOMFY_API_KEY. The Python and TypeScript snippets use the Comfy SDKs (pip install comfy-sdk, npm install @comfyorg/sdk); the cURL snippet is the same call over raw HTTP.
Model ID: wan/wan2.5-i2v-preview
Endpoint: POST https://api.comfy.org/v2/models/wan/wan2.5-i2v-preview
- Wait for the result
- Queue and collect later
Schema
Input
object
required
Enter basic information, such as prompt words, etc.
string
Audio file download URL. Supported formats: mp3 and wav. Cannot be used with reference_video_urls.
string
First frame image URL or Base64 encoded data.
Required for the wan2.5-i2v-preview and wan2.6-i2v models only. The
happyhorse-1.x i2v spellings do NOT take their first frame here: they
take it as a
media element of type first_frame (see media below),
and an img_url body that succeeds on wan2.6-i2v is refused by the
provider on happyhorse-1.0-i2v and happyhorse-1.1-i2v.
Image formats: JPEG, JPG, PNG, BMP, WEBP. Resolution: 360-2000 pixels.
File size: max 10MB.object[]
Media asset list for the wan2.7, wan3.0 and happyhorse-1.x models. Specifies reference
materials (image, audio, video) for video generation. Each element contains a type and
url field.
Supported type values vary by model:
- wan2.7-i2v: first_frame, last_frame, driving_audio, first_clip
- wan2.7-r2v: reference_image, reference_video
- wan2.7-videoedit: video, reference_image
- wan3.0-video: first_frame (max 1), last_frame (max 1), reference_image (max 10), reference_video (max 5 clips, total duration <= 15s), reference_audio (max 5 clips, total duration <= 15s), file (max 1, cannot be used with link), link (max 1, cannot be used with file). The reference_*/file/link types and first_frame/last_frame types are mutually exclusive within the same request. The array order defines the reference order of assets in the prompt (Image 1, Video 1, Audio 1, …).
- happyhorse-1.x-i2v: first_frame only, exactly 1. At least 300x300 pixels, JPEG/JPG/PNG/WEBP, max 20MB, a public URL or a data:{MIME_type};base64,… URL. These spellings take NO img_url; the first frame goes here.
- happyhorse-1.x-r2v: reference_image only, 1 to 9 of them. Shortest side at least 400 pixels, max 20MB, a public URL or a data: URL. reference_video is NOT an input type for this operation.
- happyhorse-1.x-video-edit: video The per-asset “max 20MB” figures above are the PARTNER’s ceiling on the image it ends up with, and they apply as written when the asset is a public URL, because those bytes never travel through Comfy. An INLINE data: URL does travel through Comfy and meets a lower transport ceiling first: a Comfy Router POST body is capped at 10 MiB in total and answered 413 past it, and base64 inflates a payload by about 4/3, so a single inline asset above roughly 7.5 MiB is refused before any of the partner rules here are reached — sooner still when the body carries several of them, since the 10 MiB bounds the WHOLE request rather than each element. Send anything near these ceilings as a public URL.
string
required
Media asset typePossible values:
first_frame, last_frame, driving_audio, first_clip, reference_image, reference_video, reference_audio, video, file, linkstring
required
URL of the media file: a public HTTP/HTTPS URL, an OSS temporary URL, or — where the model’s entry in the
media description above says so, as the happyhorse-1.x i2v and r2v spellings do — an inline data:{MIME_type};base64,... URL. See that description for the per-model size and pixel floors, and for the 10 MiB Router request-body cap that bounds an inline payload before any partner rule applies.string
Reverse prompt words are used to describe content that you do not want to see in the video screen
string
Text prompt words. Support Chinese and English, length not exceeding 800 characters
(up to 20,000 characters for wan3.0-video; content exceeding the limit is truncated).
For wan2.6-r2v with multiple reference videos, use ‘character1’, ‘character2’, etc. to refer to subjects
in the order of reference videos. Example: “Character1 sings on the roadside, Character2 dances beside it”
For wan3.0-video reference mode, use ‘Image 1’, ‘Video 1’, ‘Audio 1’, etc. to refer to media assets
in the corresponding order within the media array.
string[]
Reference video URLs for wan2.6-r2v model only. Array of 1-3 video URLs.
Input restrictions:
- Format: mp4, mov
- Quantity: 1-3 videos
- Single video length: 2-30 seconds
- Single file size: max 30MB
- Cannot be used with audio_url Reference duration: Single video max 5s, two videos max 2.5s each, three videos proportionally less. Billing: Based on actual reference duration used.
string
Video effect template name. Optional. Currently supported: squish, flying, carousel. When used, prompt parameter is ignored.
string
The ID of the model to call. NOT constrained on this component: Comfy Router fills it from the
{model} path segment of POST /v2/models/wan/{model}, so a Router caller omits it. A direct v1 call to POST /proxy/wan/api/v1/services/aigc/video-generation/video-synthesis MUST supply it, and the enum of accepted spellings lives on that operation’s own component, WanVideoGenerationRequest.object
Video processing parameters
boolean
default:"true"
Whether to add audio to the video
string
default:"\"auto\""
Video audio setting for wan2.7-videoedit model.
- auto (default): Model intelligently judges based on prompt content
-
origin: Forcefully preserve the original audio from the input video
Possible values:
auto,origin
integer
default:"5"
The duration of the video generated, in seconds:
- wan2.5 models: 5 or 10 seconds
- wan2.6-t2v, wan2.6-i2v: 5, 10, or 15 seconds
- wan2.6-r2v: 5 or 10 seconds only (no 15s support)
- wan2.7-i2v, wan2.7-t2v: integer in [2, 15]
- wan2.7-r2v, wan2.7-videoedit: integer in [2, 10]
-
wan3.0-video: integer in [2, 30] without video input; with video input the total
input video duration + output video duration must not exceed 30 seconds; -1 enables
smart duration mode where the model picks a suitable duration
Range:
-1to30
boolean
default:"true"
Is it enabled prompt intelligent rewriting. Default is true
string
Aspect ratio of the generated video. For wan2.7 and wan3.0 models only.
For wan2.7 models, defaults based on the resolution tier if not provided.
For wan3.0-video, adaptive (the default) automatically recommends a suitable
aspect ratio based on the input media proportions and intent.Possible values:
adaptive, 16:9, 9:16, 1:1, 4:3, 3:4string
Resolution level. Supported values vary by model:
- wan2.5-i2v-preview: 480P, 720P, 1080P
- wan2.6-i2v: 720P, 1080P only (no 480P support)
- wan2.7 models (i2v, t2v, r2v, videoedit): 720P, 1080P (default 1080P)
-
wan3.0-video, wan3.0-video-prime: 480P, 720P, 1080P (upstream default 1080P)
This proxy rejects video generation requests that provide neither resolution
nor size, because the resolution tier selects the billing rate.
Possible values:
480P,720P,1080P
integer
Random number seed, used to control the randomness of the model generated contentRange:
0 to 2147483647string
default:"\"single\""
Intelligent multi-lens control. Only active when prompt_extend is enabled.
For wan2.6 and wan2.7-r2v models.
- single: Single-shot video (default)
-
multi: Multi-shot video
Possible values:
multi,single
string
Video resolution in format widthheight. Supported resolutions vary by model:
For wan2.5 T2V: 480P (480832, 832480, 624624), 720P, 1080P sizes
For wan2.6 T2V/R2V (no 480P):
720P: 1280720, 7201280, 960960, 1088832, 8321088
1080P: 19201080, 10801920, 14401440, 16321248, 12481632
boolean
default:"false"
Whether to add a watermark logo, the watermark is located in the lower right corner
GET /v2/models/wan/wan2.5-i2v-preview/openapi.json, the same document it validates a call against before the request reaches the provider.
Output
object
required
string
Actual prompt after intelligent rewriting (for video tasks)
string
Audio URL for I2V tasks with audio generation
string
The error code for the failed request (not returned if request is successful)
string
Task completion time
string
Detailed information about the failed request (not returned if request is successful)
string
Original input prompt (for video tasks)
object[]
List of task results for image generation tasks
string
Actual prompt after intelligent rewriting (if enabled)
string
Image error code (returned when some tasks fail)
string
Image error information (returned when some tasks fail)
string
Original input prompt
string
Generated image URL address
string
Task execution time
string
Task submission time
string
required
Task ID
object
Task result statistics for image generation tasks
integer
Number of failed tasks
integer
Number of successful tasks
integer
Total number of tasks
string
required
Task statusPossible values:
PENDING, RUNNING, SUCCEEDED, FAILED, CANCELED, UNKNOWNstring
Video URL for completed video generation tasks. Link validity period 24 hours
string
required
Unique request identifier
object
Output information statistics. Only successful results are counted
integer
Video resolution level (I2V and wan3.0-video tasks)
number
Duration of generated video in seconds (I2V and wan3.0-video tasks)
integer
Frame rate of the generated video (wan3.0-video tasks)
integer
Number of generated images (T2I and I2I tasks)
number
Duration of the input video in seconds, 0.0 when no video input (wan3.0-video tasks)
number
Duration of the output video in seconds (wan3.0-video tasks)
string
Aspect ratio of the generated video, e.g. 16:9 (wan3.0-video tasks)
string
Image resolution (T2I and I2I tasks)
integer
Number of generated videos (T2V tasks)
number
Duration of generated video in seconds (T2V tasks)
string
Video resolution ratio (T2V tasks)
string
Error code for a failed request, reported at the ROOT of the envelope rather than under
output (not returned if the request succeeded).string
Detailed information about a failed request, reported at the ROOT of the envelope rather than under
output (not returned if the request succeeded). Read this before falling back to output.message.Examples
Input
Output
Before you ship
The SDKs create anIdempotency-Key and reuse it for automatic retries. For manual retries, reuse the original key. Router can hold the connection for up to 10 minutes.
When a request fails, Router sends an X-Comfy-Error-Type response header explaining why. A 422 means Router rejected the input before calling the provider. Download generated assets promptly because result URLs can expire.
Headers
Authentication, idempotency, request IDs, error buckets, retry pacing, spend limits.
Using the Router API
Model discovery, validation errors, retries, and billing.
Limitations
What Router does not do today, and what to use instead.