Skip to main content
POST

Authorization

Authorization
string
required
All API endpoints require Bearer Token authenticationGet your API Key:Visit the API Key Management Page to get your API KeyAdd it to the request header:

Request Parameters

model
string
required
Video generation model name, fixed as wan2.7-r2v
prompt
string
required
Video content description, up to 5000 charactersFor multiple images/videos, use “image 1”, “image 2”, “video 1”, etc. to reference the corresponding reference assets (in order of input)Example: "The character in image 1 enters the scene in image 2 and looks around"
image_with_roles
array<object>
Image array with roles; at least one of this and video_urls must be providedFields for each object:
  • url (string): image URL
  • role (string): image role
    • reference_image - reference image (default)
    • first_frame - specified first frame (when provided, size is ignored and the aspect ratio follows the first-frame image)
  • reference_voice (string, optional): voice sample audio URL for that reference character, used to control the character’s voice in the generated video
Example:
video_urls
array<string>
Reference video URL array, up to 5 videos (total images + videos ≤ 5)At least one of this and image_with_roles must be provided
Video constraints:
  • Format: mp4, mov
  • Duration: 1–30s
  • Resolution: width and height in the range [240, 4096] pixels
  • Aspect ratio: 1:8 – 8:1
  • File size: up to 100MB
negative_prompt
string
Negative prompt describing unwanted content, up to 500 characters
resolution
string
default:"1080P"
Video resolutionOptions:
  • 720P - Standard
  • 1080P - High definition (default)
duration
integer
default:"5"
Video duration (seconds)Supported range: 2 ~ 15 secondsDefault: 5
When the reference assets include a video: an integer between [2, 10].When the reference assets do not include a video: an integer between [2, 15].
size
string
default:"16:9"
Aspect ratioSupported formats:
  • 16:9 - Landscape widescreen (default)
  • 9:16 - Portrait
  • 1:1 - Square
  • 4:3 - Landscape
  • 3:4 - Portrait
When first_frame is provided via image_with_roles, this parameter is ignored and the aspect ratio follows the first-frame image
prompt_extend
boolean
default:"true"
Whether to enable intelligent prompt rewritingSignificantly improves results for short prompts, but increases processing timeDefault: true
watermark
boolean
default:"false"
Whether to add “AI Generated” watermark to the generated video
  • true: add watermark
  • false: no watermark (default)
seed
integer
Seed integer used to control the randomness of generated contentValue range: integer ≥0
  • For identical requests, the model generates different results when receiving different seed values (e.g., omitting seed)
  • For identical requests, the model generates similar results when receiving the same seed value, but exact consistency is not guaranteed

Response

code
integer
Response status code, 200 on success
data
array
Response data array

Use Cases

Case 1: Single Reference Image (Simplest)

Case 2: Multiple Reference Images

Case 3: Generation Based on Reference Video

Case 4: Specified First Frame + Reference Image

Case 5: Reference Image + Reference Voice (Precise)

Image Reference Rules

With multiple reference images, use numeric indices in the prompt to refer to them:
  • 1st image → “image 1” or “the first image”
  • 1st video → “video 1” or “the first video”
Query Task ResultsVideo generation is an async task that returns a task_id upon submission. Use the Get Task Status endpoint to query generation progress and results.