SkyReels 系列
- 文生视频、首尾帧、关键帧、主体与运动参考、视频延长
- 素材用
@标签在提示词里引用，提示词就是脚本 - 支持拼图参考与声纹同步
认证
All endpoints authenticate with a Bearer token.
Get an API key: open the console and create one.
Add it to the request header:
Authorization: Bearer YOUR_OAIRoute_KEY请求参数
提交成功只返回任务 ID，不含视频本身。拿成片用 task_id 轮询获取任务状态，成片地址在 result.videos[0].url，该地址约 24 小时后过期，请及时转存。
取值 skyreels-v4-fast 或 skyreels-v4-std。
必须显式传，没有默认值。
画面描述，最多 1280 token。
用到 @标签 时，标签必须同时出现在提示词里。
时长，3 到 15 秒，默认 5。
带 ref_videos 且 type 为 reference 时，改用参考视频长度，上限 10 秒。
取值 480p、720p、1080p，默认 1080p。1080p 成本远高于 480p 与 720p。
取值 16:9、4:3、1:1、9:16、3:4，默认 16:9。
图生视频与带参考视频的多模态模式下不生效。
首帧地址，格式 jpg、jpeg、png、gif、bmp。
尾帧地址，可与 first_frame_image 配对。
关键帧数组，最多 6 项，每项含 tag、image_url、time_stamp。
tag 必须以 @ 开头；time_stamp 为 -1 或落在 0 到时长之间的开区间。
参考图数组，每项含 tag、type、image_urls、可选的 audio_url。
type 取值 image 或 grid。image 时 image_urls 为 1 到 3 组、每组 1 到 5 张；grid 时只有 1 组 1 张，用于拼图参考。audio_url 只在 type 为 image 时可用，音频不超过 15 秒。
参考视频数组，最多 1 段，每项含 tag、type、video_url。
type 取值 reference 运动或主体参考、extend 视频延长。视频为 MP4 或 MOV，不超过 15 秒。
自动改写提示词，默认 true。
为 true 时先做内容审查，默认 false。
A successful submission returns only the task ID, not the video itself. Poll Get task status with the task_id; the video URL is at result.videos[0].url, expires after about 24 hours, so copy it promptly.
skyreels-v4-fast or skyreels-v4-std.
Must be passed explicitly; there's no default.
The scene description, up to 1280 tokens.
When using @tags, the tag must also appear in the prompt.
Duration, 3 to 15 seconds, default 5.
With ref_videos whose type is reference, the reference video's length is used instead, capped at 10 seconds.
480p, 720p, or 1080p, default 1080p. 1080p costs far more than 480p or 720p.
16:9, 4:3, 1:1, 9:16, or 3:4; default 16:9.
Has no effect for image to video or for multimodal mode with reference video.
The first-frame URL; formats jpg, jpeg, png, gif, bmp.
The last-frame URL; can be paired with first_frame_image.
The keyframe array, up to 6 entries, each with tag, image_url, and time_stamp.
tag must start with @; time_stamp is -1 or falls in the open interval between 0 and the duration.
The reference image array, each entry with tag, type, image_urls, and optional audio_url.
type is image or grid. For image, image_urls is 1 to 3 groups of 1 to 5 images each; for grid, exactly 1 group of 1 image, used for collage reference. audio_url works only when type is image, and the audio must be at most 15 seconds.
The reference video array, at most 1 entry, each with tag, type, and video_url.
type is reference for motion or subject reference, or extend for video extension. The video must be MP4 or MOV and at most 15 seconds.
Automatically rewrite the prompt; defaults to true.
When true, runs a content check first. Defaults to false.
模式判定
只有提示词与通用字段是文生视频。
传 first_frame_image、end_frame_image 或 mid_frame_images 走图生视频，可分别控制首帧、尾帧与关键帧。
传 ref_images 或 ref_videos 走多模态参考，覆盖主体参考、拼图参考、运动参考、视频延长与声纹同步。
图生视频字段与多模态字段不能同时出现，混用返回 422，且不计费。
Only a prompt and general fields means text to video.
Passing first_frame_image, end_frame_image, or mid_frame_images means image to video, controlling the first frame, last frame, and keyframes respectively.
Passing ref_images or ref_videos means multimodal reference, covering subject reference, collage reference, motion reference, video extension, and voiceprint sync.
Image-to-video fields and multimodal fields can't appear together; mixing them returns a 422 and isn't billed.
支持的模型列表
| 模型 ID | 定位 |
|---|---|
skyreels-v4-std | 画质优先，适合关键镜头与成片交付，价格比 Fast 高约 25 到 30% |
skyreels-v4-fast | 速度优先，适合快速预览与批量生成 |
| Model ID | Positioning |
|---|---|
skyreels-v4-std | Quality first; suited to hero shots and final deliverables, priced about 25 to 30% above Fast |
skyreels-v4-fast | Speed first; suited to quick previews and batch generation |
使用限制
ref_images里所有元素的type必须一致ref_videos最多 1 段- 带参考视频时成本约为纯文本或纯图片输入的 1.5 到 2 倍
- 参数冲突返回 422，不计费
- 目前不能同时输出音频与视频
- All entries in
ref_imagesmust share the sametype ref_videosaccepts at most 1 entry- With reference video, cost is about 1.5 to 2× a text-only or image-only input
- Conflicting parameters return a 422 and aren't billed
- Audio and video can't be output together at present
响应
提交成功返回统一的受理结构：
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}状态码，200 表示任务已受理。
本次提交的任务列表，逐项提交时按顺序排列。
受理状态，提交成功时为 submitted。
任务 ID，用它轮询结果。
A successful submission returns the standard accepted structure:
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}The status code; 200 means the task was accepted.
The list of tasks submitted this time, in order when submitting item by item.
The acceptance status; submitted on success.
The task ID; use it to poll for the result.
错误
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 请求参数无效，或参数组合冲突 |
| 401 | authentication_error | 身份验证失败，需检查 API Key |
| 402 | payment_required | 账户余额不足，需先充值 |
| 429 | rate_limit_error | 调用频率过高，稍后重试 |
参数错误在提交阶段同步返回，不创建任务、不扣费。
参数冲突或取值非法时返回 422，同样不计费。
| HTTP | type | Notes |
|---|---|---|
| 400 | invalid_request_error | Invalid parameters, or a conflicting combination |
| 401 | authentication_error | Authentication failed; check the API key |
| 402 | payment_required | Insufficient account balance; top up first |
| 429 | rate_limit_error | Too many calls; retry later |
Parameter errors are returned synchronously at submission, creating no task and charging nothing.
Conflicting or illegal values return a 422, also unbilled.
For more status codes and retry guidance see Error codes and rate limits; for troubleshooting steps on common errors see the FAQ.
查询任务
GET /v1/tasks/{task_id} 返回任务进度与结果，status 为 completed 时成片地址在 result.videos[0].url，元素带 expires_at 过期时间戳。
建议每 5 到 10 秒轮询一次，客户端总超时设为 10 到 15 分钟。status 取值 pending、processing、completed、failed、cancelled，以状态判定完成，不要依赖 progress。
失败任务自动退回费用，error.message 给出原因。
GET /v1/tasks/{task_id} returns task progress and results; once status is completed, the video URL is at result.videos[0].url, with an expires_at timestamp on the element.
Poll every 5 to 10 seconds, with a 10 to 15 minute client timeout. status is one of pending, processing, completed, failed, cancelled; judge completion by status, not by progress.
Failed tasks are refunded automatically, with the reason in error.message.