接入介绍

API 参考

开始生成

从图像生成视频

POST /v1/image_to_video

调用后平台会新建一个任务，用图像提示生成视频。

Authorization

请求头按 Bearer 方案携带 API 密钥。

Headers

X-Runway-Version：必填，必须精确写为 2024-11-06。

请求正文 Request body

• promptImage：必填。可传一个字符串，也可传对象数组。
  • 字符串 < uri >：作为视频首帧的编码图像，取 HTTPS URL 或数据 URI（图像输入细节见相关文档）。
  • 对象数组：要放进输出视频的图像集合；其中任意两张图的 position 值都不能相同。
    • uri：必填，string，< URI >，编码图像的 HTTPS URL 或数据 URI。
    • position：必填，string，取 "first" 或 "last"，分别表示该图作为视频首帧或末帧。
• model：必填，string，取 "gen3a_turbo"，即所用的模型变体。
• seed：整数，范围 [0...4294967295]；不填则随机。其他参数不变时改变 seed 可得到不同结果，同一请求用同一个 seed 会得到相近结果。
• promptText：string，长度 ≤ 512 个字符，即不超过 512 个 UTF-16 代码点的非空字符串（JavaScript 中 promptText.length === 512），用于详细描述画面中应出现的内容。
• watermark：布尔值，默认 false，表示输出视频是否带 Runway 水印。
• duration：整数，默认 10，可取 5 或 10，单位为秒。
• ratio：string，取 "1280:768" 或 "768:1280"，即输出分辨率。

响应

200：任务创建成功，响应结构为 application/json。

• id：必填，string，< 唯一标识号 >，新任务的 ID；后续用它查询状态并取回视频。

429：已超出该端点的速率限制。

获取任务详细信息

GET /v1/tasks/{id}

返回指定任务的详情。注意调用方不应期望单个任务的更新频率高于每五秒一次。

验证

Authorization：请求头按 Bearer 方案携带 API 密钥。

路径参数

• id：必填，string，< 唯一标识号 >，此前已提交且尚未取消或删除的任务 ID。

标头

• X-Runway-Version：必填，string，必须精确写为 2024-11-06。

响应

200：任务状态，响应结构为 application/json。

• id：string，< 唯一标识号 >，本次返回的任务 ID。
• status：取 "RUNNING"、"SUCCEEDED"、"FAILED"、"PENDING"、"CANCELLED"、"THROTTLED" 之一，含义如下：
  • PENDING：已入队等待执行；
  • THROTTLED：等其他任务跑完再入队；
  • RUNNING：处理中；
  • SUCCEEDED：已成功完成；
  • FAILED：执行失败；
  • CANCELLED：已中止。
• createdAt：string，< 日期时间 >，任务提交时间戳。
• failure：string，状态为 FAILED 时给出人类可读的失败原因。
• failureCode：string，状态为 FAILED 时给出机器可读错误码——以点分隔的字符串，最左段最通用，最右段最具体；例如 SAFETY.INPUT.TEXT 表示任务因输入文本的内容审核问题失败。
• output：数组，元素为 string < URI >。状态为 SUCCEEDED 时返回任务产物地址列表；地址会在 24–48 小时内失效，需重新获取任务以拿到新地址，建议把产物下载到自己的存储中保存。
• progress：数字，状态为 RUNNING 时给出 0 到 1 之间的浮点数，表示生成进度。

404：任务不存在，或已被删除/取消。