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 to the request header:

Generation Modes

SkyReels V4 auto-routes to the correct mode based on request fields — no mode field needed:
Strict mutual exclusion: I2V fields (first_frame_image / end_frame_image / mid_frame_images) and Omni fields (ref_images / ref_videos) cannot be used together, otherwise returns 422.
@tag mechanism: When using mid_frame_images / ref_images / ref_videos, each element must declare a tag starting with @ (e.g., @image1, @Actor-1, @video1), and the tag must appear in the prompt.Think of prompt as the “script” and tag as a “character pointer” to specific assets (images / videos). For example, a prompt like "@Actor-1 walks into the scene of @video1" instructs the system to inject the reference image subject tied to @Actor-1 and the motion reference tied to @video1 into the generation process.

Request Parameters

General Fields

model
string
required
Two model tiers are available:
The model field must be explicitly provided — no default value.
Pricing is strongly tied to resolution and whether ref_videos is used: 1080p is significantly more expensive than 480p / 720p; tiers with ref_videos (video input) cost ~1.5 ~ 2× compared to those without. Simultaneous audio and video output is not yet supported.
prompt
string
required
Text prompt, max 1280 tokensDescribe scenes, subjects, actions, styles in detail for better generation results.When using ref_images / ref_videos / mid_frame_images, the prompt must contain the corresponding @tag (e.g., @Actor-1, @video1, @image1).Example: "@Actor-1 walks through a neon-lit street at night."
duration
integer
default:"5"
Output video duration (seconds)
  • Range: [3, 15]
  • Default: 5
When ref_videos.type=reference is provided, duration is overridden by the reference video length (max 10 seconds).
resolution
string
default:"1080p"
Video resolutionOptions:
  • 480p
  • 720p
  • 1080p (default)
aspect_ratio
string
default:"16:9"
Aspect ratioOptions:
  • 16:9 (default)
  • 4:3
  • 1:1
  • 9:16
  • 3:4
aspect_ratio is ignored in I2V mode (output ratio is determined by the input image); also ignored when Omni is combined with ref_videos.
prompt_optimizer
boolean
default:"true"
Whether to auto-optimize the promptWhen enabled, the system automatically optimizes your prompt for better generation results.

I2V-Specific Fields

first_frame_image
string
First frame image URL (jpg / jpeg / png / gif / bmp)When provided, this image is used as the starting frame of the video.
end_frame_image
string
End frame image URL (jpg / jpeg / png / gif / bmp)When provided, this image is used as the ending frame of the video. Can be combined with first_frame_image for first-and-last-frame control.
mid_frame_images
object[]
Mid keyframe list, up to 6. Each element has the following structure:

Omni-Specific Fields

ref_images
object[]
Reference image list (all elements must share the same type). Each element has the following structure:
ref_videos
object[]
Reference video list, up to 1. Each element has the following structure:

Supported Scenarios

The following scenarios are supported by both skyreels-v4-fast and skyreels-v4-std:

Parameter Constraints

Violating any of the following will cause the request to be rejected with a 422 response, no billing occurs:

Response

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

Request Examples

Case 1: Text-to-Video (Minimal)

Case 2: Text-to-Video (Full Parameters)

Case 3: Image-to-Video - First Frame

Case 4: Image-to-Video - First/End Frame + Mid Keyframes

Case 5: Omni - Single Subject Reference

Case 6: Omni - Multi-Subject + Video Motion Reference

This case uses ref_videos.type=reference, so the requested duration will be overridden by the actual reference video length (max 10 seconds). Even though "duration": 5 is passed here, the final video length follows the reference video.

Case 7: Omni - Grid Collage

Case 8: Omni - Video Extension (extend)

Case 9: Omni - Audio Sync (Voice-Driven)

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.