Skip to main content
  • 支持文生视频（T2V）、图生视频（I2V）、多模态参考（Omni）三种模式，由传参自动路由
  • 支持 480p / 720p / 1080p 分辨率，3 ~ 15 秒时长
  • 支持首帧/尾帧/关键帧、参考图、参考视频、拼贴图、视频扩展、声纹同步等高阶能力
  • 异步处理模式，返回任务 ID 用于后续查询
curl --request POST \
  --url https://claw.dualseason.com/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "skyreels-v4-fast",
    "prompt": "A serene forest at sunset with golden light filtering through the trees.",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "prompt_optimizer": true
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KPEY5H3NQ2W8D7T6VB3F9GR4"
    }
  ]
}

​
认证

​
Authorization
string
required
所有接口均需要使用 Bearer Token 进行认证获取 API Key：访问 API Key 管理页面 获取您的 API Key使用时在请求头中添加：
Authorization: Bearer YOUR_API_KEY

​
生成模式

SkyReels V4 通过请求字段自动路由到对应模式，无需指定 mode 字段：
模式触发条件能力
T2V（文生视频）只传 prompt 及通用字段纯文本驱动生成
I2V（图生视频）传入 first_frame_image / end_frame_image / mid_frame_images 任一首帧、尾帧、关键帧控制
Omni（多模态参考）传入 ref_images / ref_videos 任一主体参考、拼贴图、动作参考、视频扩展、声纹同步
严格互斥：I2V 字段（first_frame_image / end_frame_image / mid_frame_images）与 Omni 字段（ref_images / ref_videos）不能同时出现，否则返回 422。
@tag 机制：当使用 mid_frame_images / ref_images / ref_videos 时，每个元素需声明一个以 @ 开头的 tag（如 @image1、@Actor-1、@video1），并且 tag 必须出现在 prompt 中。可以把 prompt 理解为”剧本”，tag 则是指向具体素材（图片 / 视频）的”角色指针”—— 例如 prompt 写 "@Actor-1 走进 @video1 的场景"，系统据此将 @Actor-1 对应的参考图主体和 @video1 对应的动作参考注入到生成过程。

​
请求参数

​
通用字段

​
model
string
required
支持以下两个档位：
模型定位适用场景
skyreels-v4-fast速度优先快速预览、批量生成、日常内容
skyreels-v4-std质量优先（价格较 Fast 高 25~30%）关键画面、细节要求高、正式交付
必须显式传递 model 字段，无默认值。
计费与分辨率、是否使用 ref_videos 强相关：1080p 价格显著高于 480p / 720p；传入 ref_videos（带视频输入）的档位约为无视频输入的 1.5 ~ 2 倍。暂不支持音频和视频同时输出。
​
prompt
string
required
文本提示词，最长 1280 tokens建议详细描述场景、主体、动作、风格等，以获得更好的生成效果。使用 ref_images / ref_videos / mid_frame_images 时，prompt 中必须包含 对应的 @tag（如 @Actor-1、@video1、@image1）。示例："@Actor-1 walks through a neon-lit street at night."
​
duration
integer
default:"5"
输出视频时长（秒）
  • 取值范围：[3, 15]
  • 默认值：5
当传入 ref_videos.type=reference 时，duration 会被参考视频长度覆盖（上限 10 秒）。
​
resolution
string
default:"1080p"
视频分辨率可选值：
  • 480p
  • 720p
  • 1080p（默认）
​
aspect_ratio
string
default:"16:9"
宽高比可选值：
  • 16:9（默认）
  • 4:3
  • 1:1
  • 9:16
  • 3:4
I2V 模式下 aspect_ratio 会被忽略（输出比例由输入图决定）；Omni 带 ref_videos 时同样忽略。
​
prompt_optimizer
boolean
default:"true"
是否自动优化 prompt启用后，系统会自动优化您的提示词以获得更好的生成效果。

​
I2V 专用字段

​
first_frame_image
string
视频起始帧图片 URL（jpg / jpeg / png / gif / bmp）传入后将以该图片作为视频的起始画面。
​
end_frame_image
string
视频结束帧图片 URL（jpg / jpeg / png / gif / bmp）传入后将以该图片作为视频的结束画面，可与 first_frame_image 组合实现首尾帧控制。
​
mid_frame_images
object[]
中间关键帧列表，最多 6 个。每个元素结构如下：

​
Omni 专用字段

​
ref_images
object[]
参考图列表（所有元素 type 必须一致）。每个元素结构如下：
​
ref_videos
object[]
参考视频列表，最多 1 个。每个元素结构如下：

​
支持的生成场景

以下场景 skyreels-v4-fast 和 skyreels-v4-std 均支持：
场景模式必填参数典型用例
文生视频T2Vprompt纯文本描述驱动，快速生成概念镜头
图生视频 - 首帧I2Vfirst_frame_image静图转视频，指定起始画面
图生视频 - 尾帧I2Vend_frame_image指定视频收束画面
图生视频 - 关键帧I2Vmid_frame_images（1 ~ 6）首 + 尾 + 中间关键帧，精准控制分镜节奏
Omni 单/多主体参考Omniref_images（type=image）角色一致性、多主体同框
Omni 拼贴图Omniref_images（type=grid，1 张）分步流程视频（教程、菜谱、操作示范）
Omni 动作参考Omniref_videos（type=reference）复刻参考视频的动作、主体或风格
Omni 视频扩展Omniref_videos（type=extend）从已有视频续写后续剧情
Omni 声纹同步Omniref_images（type=image）+ audio_url数字人口播、音频驱动对口型

​
参数约束

以下约束违反时请求将被拒绝并返回 422，且 不产生计费：
参数约束
prompt最长 1280 tokens
duration[3, 15] 秒；带 ref_videos.type=reference 时被参考视频长度覆盖（上限 10 秒）
resolution仅 480p / 720p / 1080p
aspect_ratio16:9 / 4:3 / 1:1 / 9:16 / 3:4；I2V 忽略；Omni 带 ref_videos 时忽略
mid_frame_images最多 6 个；time_stamp 必须为 -1 或落在 (0, duration) 区间
ref_images 整体列表内 type 必须一致；不能与 I2V 字段同时出现
ref_images.type=grid列表长度必须 = 1；image_urls 必须为 1 张
ref_images.type=image列表长度 1 ~ 3；每项 image_urls 长度 1 ~ 5
ref_images.audio_url仅 type=image 支持，音频 ≤ 15 秒
ref_videos最多 1 个；video_url MP4 / MOV，≤ 15 秒
ref_videos.type=reference覆盖请求 duration（最长 10 秒），可与 ref_images.type=image 组合，默认带入输入视频音频
ref_videos.type=extend按请求 duration 计费；不能与 ref_images 组合
tag 字段必须以 @ 开头且出现在 prompt 中
I2V / Omni 互斥I2V 字段与 Omni 字段不能同时出现

​
响应

​
code
integer
响应状态码，成功时为 200
​
data
array
返回数据数组

​
请求示例

​
场景 1：文生视频（最简）

{
  "model": "skyreels-v4-fast",
  "prompt": "A serene forest at sunset with golden light filtering through the trees."
}

​
场景 2：文生视频（完整参数）

{
  "model": "skyreels-v4-std",
  "prompt": "A serene forest at sunset.",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "prompt_optimizer": true
}

​
场景 3：图生视频 - 首帧

{
  "model": "skyreels-v4-fast",
  "prompt": "Slowly pull the camera back to reveal the entire scene.",
  "first_frame_image": "https://example.com/start.png",
  "duration": 5
}

​
场景 4：图生视频 - 首尾帧 + 中间关键帧

{
  "model": "skyreels-v4-std",
  "prompt": "The King summons a flying dragon. @image1 The dragon lowers. The King mounts and flies away.",
  "duration": 8,
  "resolution": "1080p",
  "first_frame_image": "https://example.com/k2v_0.png",
  "end_frame_image":   "https://example.com/k2v_2.png",
  "mid_frame_images": [
    { "tag": "@image1", "image_url": "https://example.com/k2v_1.png", "time_stamp": 3 }
  ]
}

​
场景 5：Omni - 单主体参考

{
  "model": "skyreels-v4-fast",
  "prompt": "@Actor-1 walks through a neon-lit street at night.",
  "ref_images": [
    { "tag": "@Actor-1", "type": "image", "image_urls": ["https://example.com/actor.jpg"] }
  ]
}

​
场景 6：Omni - 多主体 + 视频动作参考

{
  "model": "skyreels-v4-fast",
  "prompt": "The man from @image_1 imitates the move on the left in @video_1. The woman from @image_2 imitates the right side.",
  "duration": 5,
  "ref_images": [
    { "tag": "@image_1", "type": "image", "image_urls": ["https://example.com/a.png"] },
    { "tag": "@image_2", "type": "image", "image_urls": ["https://example.com/b.png"] }
  ],
  "ref_videos": [
    { "tag": "@video_1", "type": "reference", "video_url": "https://example.com/motion.mp4" }
  ]
}
此场景使用 ref_videos.type=reference，请求的 duration 会被参考视频实际长度覆盖（上限 10 秒）。即便此处传 "duration": 5，最终视频长度以参考视频为准。

​
场景 7：Omni - 拼贴图（grid）

{
  "model": "skyreels-v4-fast",
  "prompt": "Create a video showing how to make tomato and egg noodles based on @image1.",
  "ref_images": [
    { "tag": "@image1", "type": "grid", "image_urls": ["https://example.com/recipe_grid.png"] }
  ]
}

​
场景 8：Omni - 视频扩展（extend）

{
  "model": "skyreels-v4-fast",
  "prompt": "Video extended @video1, someone walks over and sits on the sofa.",
  "duration": 8,
  "ref_videos": [
    { "tag": "@video1", "type": "extend", "video_url": "https://example.com/source.mp4" }
  ]
}

​
场景 9：Omni - 带声纹（语音同步）

{
  "model": "skyreels-v4-std",
  "prompt": "@Actor-1 speaks with a calm tone.",
  "ref_images": [
    {
      "tag": "@Actor-1",
      "type": "image",
      "image_urls": ["https://example.com/actor.jpg"],
      "audio_url":  "https://example.com/voice.mp3"
    }
  ]
}
查询任务结果视频生成为异步任务，提交后会返回 task_id。使用 获取任务状态 接口查询生成进度和结果。