接口说明

RayWorld R1。
视频生成接口。

视频接口通过多模态 content 数组输入（文本 / 图片 / 视频 / 音频）。创建、查询、列表、取消或删除共用同一套任务对象。Context-IR 只产出增强提示词；再生成把符合 768p 规格的源视频升到 2k。最高 2k。相机位姿与相机路径是 RayWorld 扩展。

鉴权

在请求头携带 API Key：Authorization: Bearer sk-...。完整密钥只在创建时显示一次。

Authorization: Bearer sk-...

x-api-key: sk-...

POST

创建视频生成

/api/v1/contents/generations/tasks

模型依据传入的文本、图片、视频、音频生成视频。创建成功后返回 task_id，用查询接口轮询。

model

string

必填。当前可用 rayworld-r1（RayWorld R1）。

content

array

必填。多模态输入。每项用 type 区分 text / image_url / video_url / audio_url，用 role 标注用途。必须包含一个非空 text。

resolution

string

必填。480p / 768p / 2k。720p 视为 768p，1080p 视为 2k。

duration

integer

必填。生成时长，整数秒。RayWorld R1：4–15。

ratio

string

可选。adaptive / 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16。文生视频必填且不能 adaptive；图生视频恒为 adaptive。

extra

object

可选。当前支持 prompt_expansion_mode：disabled / balanced / quality，默认 balanced。

aigc_watermark

boolean

可选。是否添加显式 AIGC 水印，默认 false。依法所需的其他标识仍可能添加。

callback_url

string

可选。任务状态变更时 POST 通知。服务器会先发 challenge 校验，需 3 秒内原样返回。

camera_mode

string

可选。RayWorld 扩展：reshoot / gimbal / path / multicam。

camera

object

可选。随 camera_mode 变化，见「相机控制」。

curl -X POST "$HOST/api/v1/contents/generations/tasks" \
  -H "Authorization: Bearer $RAYWORLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rayworld-r1",
    "content": [{ "type": "text", "text": "黄昏湖边一座木屋，我站在栈桥上可以环顾" }],
    "resolution": "768p",
    "duration": 5,
    "ratio": "16:9"
  }'

成功响应只需要记下 task_id，再去查询。

{
  "task_id": "cgt-20260921-8f21ab"
}

计费

创建视频时按分辨率扣积分。积分 = 计费秒数 × 秒价。计费秒数就是请求里的 duration（4–15 的整数秒）。分辨率用模型实际档位：480p、768p、2k。传入 720p 按 768p 计价，传入 1080p 按 2k 计价。

分辨率	积分 / 秒	5 秒	15 秒
480p	3	15	45
768p	6	30	90
2k	10	50	150

参考图（role=reference_image）前 5 张含在秒价里，从第 6 张起每张加 2 积分。首帧、尾帧、参考视频和参考音频不加这笔。再生成按 2k 秒价，对源视频时长计费。Context-IR 固定 2 积分。排队中取消不扣费。体验台和 API 用同一张秒价。

输入组合

每次请求必须包含一个非空 text。按 content 里的 type / role 区分场景。

场景	content	ratio
文生视频	仅一个 text	必填，且不能是 adaptive
图生视频 · 首帧	text + 1 张 image_url（role=first_frame 或不填）	恒为 adaptive
图生视频 · 尾帧	text + 1 张 image_url（role=last_frame）	恒为 adaptive
图生视频 · 首尾帧	text + 2 张 image_url（first_frame / last_frame）	恒为 adaptive
多模态参考	text + reference_image / reference_video / reference_audio	可选，默认 adaptive

图生视频与多模态参考生视频互斥：出现 reference_image / reference_video / reference_audio 任一 role，就不能再出现 first_frame / last_frame，反之亦然。

请求示例

下面几组对应文生、图生和多模态参考的常见组合。相机字段是 RayWorld 扩展，可叠加在同一任务上。

文生视频

content 仅含 text。ratio 必填，不能为 adaptive。

{
  "model": "rayworld-r1",
  "content": [
    {
      "type": "text",
      "text": "黄昏湖边一座木屋，栈桥伸进水面。我站在桥上，可以转头看见松林、晚霞和倒影。"
    }
  ],
  "resolution": "768p",
  "duration": 5,
  "ratio": "16:9"
}

图生视频 · 首帧

一张图。role=first_frame；仅一张图且不填 role 时，按 first_frame 处理。ratio 恒为 adaptive，传入其他值会被忽略。

{
  "model": "rayworld-r1",
  "content": [
    {
      "type": "text",
      "text": "女孩抱着狐狸看向镜头，头发被风吹起，镜头慢慢拉远。"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first.jpg" },
      "role": "first_frame"
    }
  ],
  "resolution": "768p",
  "duration": 5,
  "ratio": "adaptive"
}

图生视频 · 尾帧

一张图，role=last_frame。

{
  "model": "rayworld-r1",
  "content": [
    { "type": "text", "text": "从栈桥走到木屋门口，光线从黄昏变成灯火。" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/last.jpg" },
      "role": "last_frame"
    }
  ],
  "resolution": "768p",
  "duration": 5,
  "ratio": "adaptive"
}

图生视频 · 首尾帧

两张图，role 分别为 first_frame / last_frame。宽高比不一致时以首帧为准。

{
  "model": "rayworld-r1",
  "content": [
    { "type": "text", "text": "从栈桥走到木屋门口，光线从黄昏变成灯火。" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first.jpg" },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/last.jpg" },
      "role": "last_frame"
    }
  ],
  "resolution": "768p",
  "duration": 8,
  "ratio": "adaptive"
}

多模态参考 · 参考图

每张 role=reference_image，最多 9 张。可与参考视频、参考音频混合。不可与 first_frame / last_frame 同用。

{
  "model": "rayworld-r1",
  "content": [
    { "type": "text", "text": "保持参考图里的木屋和人物，镜头沿湖岸右环绕。" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/ref-1.jpg" },
      "role": "reference_image"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/ref-2.jpg" },
      "role": "reference_image"
    }
  ],
  "resolution": "768p",
  "duration": 10,
  "ratio": "16:9",
  "camera_mode": "path",
  "camera": { "path": "orbit-right" }
}

多模态参考 · 参考视频 + 参考音频

视频、音频各最多 3 段，单段 2–15 秒，合计不超过 15 秒。

{
  "model": "rayworld-r1",
  "content": [
    { "type": "text", "text": "沿参考视频的运动继续走，对白说：\"别回头。\"" },
    {
      "type": "video_url",
      "video_url": { "url": "https://example.com/clip.mp4" },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": { "url": "https://example.com/line.mp3" },
      "role": "reference_audio"
    }
  ],
  "resolution": "768p",
  "duration": 5,
  "ratio": "adaptive"
}

GET

查询任务

/api/v1/contents/generations/tasks/:task_id

按 task_id 查询最近 7 天内单个任务。窗口为 [T-7天, T)，T 为请求时刻的 UTC 秒级时间戳；超出窗口返回 invalid task_id。视频任务成功后从 task.content.url 取片；Context-IR 成功后从 task.content.prompt 取增强提示词。链接有时效，请及时转存。状态：queued / running / succeeded / failed / cancelled。

同一查询接口覆盖三种 task_type：generation（视频生成）、context_ir（Context-IR）、regeneration（再生成）。modality 分别为 video / text / video。

查询成功响应

{
  "task": {
    "id": "cgt-20260921-8f21ab",
    "model": "rayworld-r1",
    "status": "succeeded",
    "created_at": 1779348818,
    "updated_at": 1779348874,
    "content": {
      "url": "https://cdn.example.com/out.mp4"
    },
    "resolution": "768p",
    "duration": 5,
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 0
    },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}

Context-IR 成功

{
  "task": {
    "id": "cgt-20260921-ir01",
    "model": "rayworld-r1",
    "status": "succeeded",
    "created_at": 1779349000,
    "updated_at": 1779349028,
    "content": {
      "prompt": "integrated_multimodal_description: [Shot 1] Cinematic wide shot...\noverall_soundscape: ...\nnon_diegetic_music: ..."
    },
    "duration": 5,
    "usage": {
      "total_tokens": 9090,
      "prompt_tokens": 5664,
      "completion_tokens": 3426
    },
    "ratio": "16:9",
    "task_type": "context_ir",
    "modality": "text"
  }
}

再生成成功

{
  "task": {
    "id": "cgt-20260921-rg01",
    "model": "rayworld-r1",
    "status": "succeeded",
    "created_at": 1779349100,
    "updated_at": 1779349400,
    "content": {
      "url": "https://cdn.example.com/r1-2k.mp4"
    },
    "resolution": "2k",
    "duration": 5,
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 0
    },
    "ratio": "",
    "task_type": "regeneration",
    "modality": "video"
  }
}

失败

{
  "task": {
    "id": "cgt-20260921-8f21ac",
    "model": "rayworld-r1",
    "status": "failed",
    "error": {
      "code": "1026",
      "message": "video description contains sensitive content"
    },
    "created_at": 1779348818,
    "updated_at": 1779348900,
    "resolution": "768p",
    "duration": 5,
    "usage": {},
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}

GET

查询任务列表

/api/v1/contents/generations/tasks

分页查询最近 7 天内的任务。可按状态、任务 ID、模型和任务类型过滤。

page_num

integer

可选。页码，从 1 开始，默认 1。

page_size

integer

可选。每页数量，默认 20，最大 100。

filter.status

string

可选。queued / running / succeeded / failed / cancelled。

filter.task_ids

string[]

可选。按任务 ID 过滤，可传多个。

filter.model

string

可选。按模型过滤，如 rayworld-r1。

filter.task_type

string

可选。generation / context_ir / regeneration。

curl --request GET \
  --url "$HOST/api/v1/contents/generations/tasks?page_num=1&page_size=20&filter.task_type=generation" \
  -H "Authorization: Bearer $RAYWORLD_API_KEY"

{
  "items": [
    {
      "id": "cgt-20260921-8f21ab",
      "model": "rayworld-r1",
      "status": "succeeded",
      "created_at": 1779348818,
      "updated_at": 1779348874,
      "content": { "url": "https://cdn.example.com/out.mp4" },
      "resolution": "768p",
      "duration": 5,
      "usage": { "total_seconds": 5, "output_seconds": 5 },
      "ratio": "16:9",
      "task_type": "generation",
      "modality": "video"
    },
    {
      "id": "cgt-20260921-ir01",
      "model": "rayworld-r1",
      "status": "succeeded",
      "content": { "prompt": "integrated_multimodal_description: ..." },
      "duration": 5,
      "task_type": "context_ir",
      "modality": "text"
    }
  ],
  "total": 24
}

DELETE

取消或删除任务

/api/v1/contents/generations/tasks/:task_id

按当前状态自动执行取消或删除。running 与 cancelled 不可操作。

status	action	说明
queued	cancelled	取消排队中的任务，尚未开始处理。
succeeded	deleted	删除成功任务记录。
failed	deleted	删除失败任务记录。
running	—	不可操作。
cancelled	—	不可操作。

queued → cancelled，尚未开始处理，不扣费。

succeeded / failed → deleted，删除任务记录。

running / cancelled 返回 400，不可操作。

{
  "task_id": "cgt-20260921-8f21ab",
  "action": "cancelled",
  "status": "cancelled"
}

{
  "task_id": "cgt-20260921-8f21ab",
  "action": "deleted",
  "status": "deleted"
}

POST

创建 Context-IR

/api/v1/contents/generations/context-ir

深度理解文本、图片、视频、音频，生成结构化、语义更丰富的视频提示词。本接口不创建视频任务。创建成功后用查询接口取结果；成功时 task_type 为 context_ir，从 content.prompt 读取增强提示词。

content 组合与创建视频相同：文生、图生、多模态参考。必须包含非空 text。duration 必填，4–15 秒。文生视频 ratio 必填且不能 adaptive。

model

string

必填。当前可用 rayworld-r1。

content

array

必填。与创建视频相同的多模态数组，必须包含一个非空 text。

duration

integer

必填。目标视频时长，4–15。

ratio

string

可选。默认 adaptive。文生视频必填且不能 adaptive；图生视频恒为 adaptive。

callback_url

string

可选。任务状态变更时 POST 通知，先发 challenge 校验。

curl -X POST "$HOST/api/v1/contents/generations/context-ir" \
  -H "Authorization: Bearer $RAYWORLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rayworld-r1",
    "content": [{ "type": "text", "text": "黄昏湖边一座木屋，栈桥伸进水面。我站在桥上，可以转头看见松林、晚霞和倒影。" }],
    "duration": 5,
    "ratio": "16:9"
  }'

{
  "model": "rayworld-r1",
  "content": [
    { "type": "text", "text": "黄昏湖边一座木屋，栈桥伸进水面。我站在桥上，可以转头看见松林、晚霞和倒影。" }
  ],
  "duration": 5,
  "ratio": "16:9"
}

成功响应只需要记下 task_id，再去查询。

{
  "task_id": "cgt-20260921-8f21ab"
}

POST

创建视频再生成

/api/v1/contents/generations/regenerate

把符合 RayWorld R1 768p 输出规格的源视频再生成为 2k。source_task_id 与 content（含 base_video）必须且只能提供其一。task_type 为 regeneration，仍用查询 / 列表 / 删除接口管理。

两种输入：按已有成功任务的 source_task_id（须属于当前账号、succeeded、仍在 7 天窗口内）；或在 content 里提交生成 768p 时的全部输入，外加 1 个 role=base_video 的源视频。

base_video 须含音轨、24 fps、宽高能被 32 整除，面积在 768×768 到 768×1344，总帧数 107–362（约 4–15 秒）。不支持任意视频的通用处理。text 必须是当时送入模型的最终 prompt，不要用 Context-IR 处理前的原文。

model

string

必填。当前可用 rayworld-r1。

source_task_id

string

与 content 二选一。已有成功视频生成任务的 task_id。

content

array

与 source_task_id 二选一。须原样附上 768p 生成时的输入，并含 1 个 role=base_video。

resolution

string

必填。当前支持 2k。

aigc_watermark

boolean

可选。是否添加显式 AIGC 水印，默认 false。依法所需的其他标识仍可能添加。

callback_url

string

可选。任务状态变更回调，行为同创建视频。

curl -X POST "$HOST/api/v1/contents/generations/regenerate" \
  -H "Authorization: Bearer $RAYWORLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rayworld-r1",
    "source_task_id": "cgt-20260921-8f21ab",
    "resolution": "2k"
  }'

source_task_id

{
  "model": "rayworld-r1",
  "source_task_id": "cgt-20260921-8f21ab",
  "resolution": "2k"
}

base_video

{
  "model": "rayworld-r1",
  "content": [
    { "type": "text", "text": "黄昏湖边一座木屋，栈桥伸进水面。我站在桥上，可以转头看见松林、晚霞和倒影。" },
    {
      "type": "video_url",
      "video_url": { "url": "https://cdn.example.com/r1-768p.mp4" },
      "role": "base_video"
    }
  ],
  "resolution": "2k"
}

成功响应只需要记下 task_id，再去查询。

{
  "task_id": "cgt-20260921-8f21ab"
}

content 约束

type	字段	限制
text	text	必填，描述期望生成的视频。按字符计，单个 text 最多 7000 字。对白写在双引号里。
image_url	image_url.url · role	JPG / JPEG / PNG / WEBP / HEIC / HEIF；单张 ≤30MB；宽高 256–5760；宽高比 0.4–2.5。首帧 ≤1、尾帧 ≤1、参考图 ≤9。
video_url	video_url.url · role	MP4 / MOV；H.264 或 H.265；单段 ≤50MB；个数 ≤3；单段 2–15 秒，总时长 ≤15 秒；宽高 256–5760；宽高比 0.4–2.5；帧率 23.976–60。role 固定 reference_video。
audio_url	audio_url.url · role	WAV / MP3；单段 ≤15MB；个数 ≤3；单段 2–15 秒，总时长 ≤15 秒。role 固定 reference_audio。

整包请求体不超过 64MB。大文件用公网 URL，不要走 Base64（会放大约 33%）。

相机控制

四种相机模式是 RayWorld 在同一创建接口上的扩展。相机几何是原生输入，不是粗粒度文本指令。先锁定场景，再指定相机位姿或相机路径。

camera_mode	camera	说明
reshoot	{ "instruction": "same world, new viewpoint" }	重拍：同一场景，指定新视角。
gimbal	{ "yaw": 35, "pitch": -8 }	云台：指定相机角度，yaw ±180，pitch ±40。
path	{ "path": "orbit-right" }	路径：设计相机路径，orbit-right / push-in / crane-up / track-left。
multicam	{ "rig": ["front", "left", "right", "rear"] }	多机位：同一时刻多视角重取景。

错误码

400

参数错误：缺少 text、role 混用、时长或分辨率不合法、invalid task_id，或任务处于不可取消/删除的状态

401

鉴权失败：请求头未携带有效 API Key

402

余额或额度不足

403

还在白名单里，不能生成或建 Key

404

任务不存在，或不属于当前账号

422

输入涉及敏感内容

429

触发限流，请稍后重试

500

服务端错误

先申请白名单，再在控制台创建 Key。

RayWorld R1。视频生成接口。

鉴权

创建视频生成

计费

输入组合

请求示例

文生视频

图生视频 · 首帧

图生视频 · 尾帧

图生视频 · 首尾帧

多模态参考 · 参考图

多模态参考 · 参考视频 + 参考音频

查询任务

查询成功响应

Context-IR 成功

再生成成功

失败

查询任务列表

取消或删除任务

创建 Context-IR

创建视频再生成

source_task_id

base_video

content 约束

相机控制

错误码

RayWorld R1。
视频生成接口。