SpeedyRPM

外观

视频生成 ​

视频生成使用异步任务接口。提交成功后先保存响应中的视频 ID，再轮询任务状态；状态变为 completed 后下载 MP4 文件。

图生视频示例 ​

下面的请求使用本地图片作为首个参考素材：

bash
curl --fail-with-body https://relay.withrpm.org/v1/videos \
  -H "Authorization: Bearer $SPEEDYRPM_API_KEY" \
  -F "model=veo-3.1-i2v-fast" \
  -F "prompt=镜头缓慢向前移动，保持主体外观一致" \
  -F "input_reference=@./reference.jpg;type=image/jpeg" \
  -F "seconds=8" \
  -F "size=1280x720"

veo-3.1-i2v 和 veo-3.1-i2v-fast 是图生视频模型，必须提供 input_reference，并使用 seconds=8。示例中的模型是否可用仍应以当前 API Key 调用 /v1/models 的结果为准。

这两个 Veo 模型仅支持固定 8 秒，不支持 6 秒或其他时长。传入非 8 秒值会返回 HTTP 400，并在 error.message 中说明固定时长要求；客户端应修正参数，不应按网关故障重试。

Hailuo 3.0 图生视频同样使用异步接口，例如：

bash
curl --fail-with-body https://relay.withrpm.org/v1/videos \
  -H "Authorization: Bearer $SPEEDYRPM_API_KEY" \
  -F "model=hailuo-video-3.0-i2v" \
  -F "prompt=镜头缓慢向前移动，保持主体外观一致" \
  -F "input_reference=@./reference.jpg;type=image/jpeg" \
  -F "seconds=4" \
  -F "size=1280x768"

提交成功会返回异步任务对象。字段可能随任务进度更新，客户端至少应保存 id 并检查 status：

json
{
  "id": "<VIDEO_ID>",
  "object": "video",
  "model": "veo-3.1-i2v-fast",
  "status": "in_progress",
  "progress": 1,
  "stage": "preparing",
  "eta_seconds": null,
  "progress_updated_at": 1787192104,
  "seconds": "8",
  "size": "1280x720"
}

文生视频示例 ​

不带参考素材的模型可以使用 multipart 表单提交文生视频任务：

bash
curl --fail-with-body https://relay.withrpm.org/v1/videos \
  -H "Authorization: Bearer $SPEEDYRPM_API_KEY" \
  -F "model=seedance-2.0-mini" \
  -F "prompt=清晨的海边，镜头沿着沙滩平稳前进" \
  -F "seconds=4" \
  -F "size=854x480"

不同模型允许的时长、尺寸和参考素材不同。不要把一个模型的参数直接用于另一个模型。

模型档位 ​

下表列出当前视频模型的固定约束。模型是否对某个 API Key 开放，仍以该 API Key 调用 /v1/models 的结果为准。

模型输出时长分辨率档位参考素材
hailuo-video-3.0-t2v4–15 秒，按整秒设置768p、1440p文生视频，无需参考素材
hailuo-video-3.0-i2v4–15 秒，按整秒设置768p、1440p需要参考素材
hailuo-video-3.0-extend4–15 秒，按整秒设置仅 1440p需要参考视频；参考视频时长参与计费
seedance-2.04–15 秒，按整秒设置480p、720p、1080p、4K最多 12 个参考素材，其中参考视频最多 3 个；参考视频时长参与计费
seedance-2.0-fast4–15 秒，按整秒设置480p、720p最多 12 个参考素材，其中参考视频最多 3 个；参考视频时长参与计费
seedance-2.0-mini4–15 秒，按整秒设置480p、720p最多 12 个参考素材，其中参考视频最多 3 个；参考视频时长参与计费
veo-3.1-i2v固定 8 秒，不可调整720p、1080p、4K需要参考图
veo-3.1-i2v-fast固定 8 秒，不可调整720p、1080p、4K需要参考图

请求字段 ​

字段类型必填说明
modelstring是/v1/models 返回的视频模型 ID
promptstring是视频内容描述
input_referencefile图生视频必填单张参考图片；示例使用 JPEG
secondsinteger是输出时长，取值由模型决定
sizestring是宽x高，例如 1280x720

参考素材总大小不能超过 50 MB。生产客户端还应为提交、轮询和下载分别设置超时。

查询任务 ​

bash
curl --fail-with-body \
  -H "Authorization: Bearer $SPEEDYRPM_API_KEY" \
  "https://relay.withrpm.org/v1/videos/<VIDEO_ID>"

支持丰富进度的任务会在同一个查询响应中返回以下字段，不需要调用额外的进度接口：

json
{
  "id": "<VIDEO_ID>",
  "object": "video",
  "status": "in_progress",
  "progress": 47,
  "stage": "generating",
  "eta_seconds": 38,
  "progress_updated_at": 1787192104
}
字段类型说明
statusstring任务状态；终态为 completed 或 failed
progressinteger 或 null0–100 的进度百分比；不具备精确进度能力的渠道可能返回粗略值或 null
stagestring，可选当前阶段；支持值见下表
eta_secondsinteger 或 null，可选预计剩余秒数；未知或预测已失效时为 null
progress_updated_atinteger，可选进度快照实际推进时的 Unix 秒时间戳，不是本次 HTTP 响应时间

丰富进度的阶段如下：

阶段含义
preparing正在准备生成任务
generating正在生成视频
finalizing正在整理、下载或保存成品
completed成品已经可以下载
failed任务失败

客户端必须允许 stage、eta_seconds 和 progress_updated_at 缺失。没有数字进度时应显示不确定进度条，不要自行虚构百分比或 ETA。

下面是一个最小轮询示例：

js
async function waitForVideo(videoId, apiKey) {
  let delayMs = 5000;

  while (true) {
    const response = await fetch(
      `https://relay.withrpm.org/v1/videos/${encodeURIComponent(videoId)}`,
      { headers: { Authorization: `Bearer ${apiKey}` } },
    );
    if (!response.ok) {
      throw new Error(`query failed: HTTP ${response.status}`);
    }

    const video = await response.json();
    renderProgress({
      status: video.status,
      progress: video.progress ?? null,
      stage: video.stage ?? null,
      etaSeconds: video.eta_seconds ?? null,
      updatedAt: video.progress_updated_at ?? null,
    });

    if (video.status === "completed") return video;
    if (video.status === "failed") {
      throw new Error(video.error?.message ?? "video generation failed");
    }

    await new Promise((resolve) => setTimeout(resolve, delayMs));
    delayMs = Math.min(15000, Math.round(delayMs * 1.2));
  }
}

常见状态如下：

状态含义客户端处理
pending等待进入队列继续轮询
queued已进入队列继续轮询
in_progress正在生成或整理结果继续轮询
completed已完成下载视频
failed任务失败读取 error，不要无限重试同一请求

建议从 5 秒轮询间隔开始，并逐步放慢到 10–15 秒；不要高频查询。连续响应的 progress_updated_at 相同表示尚无新进度快照，这不是错误。任务 ID 只允许创建它的 API Key 所属账户查询。

下载视频 ​

任务状态变为 completed 后下载内容：

bash
curl --fail-with-body -L \
  -H "Authorization: Bearer $SPEEDYRPM_API_KEY" \
  "https://relay.withrpm.org/v1/videos/<VIDEO_ID>/content" \
  -o output.mp4

下载接口返回 video/mp4。视频结果有保存期限，应用应在任务完成后及时下载到自己的存储中；在任务尚未完成时调用下载接口会返回错误。

失败与重试 ​

参数错误使用统一的 OpenAI 风格响应。以下示例表示请求的 1 秒不在 Hailuo 3.0 支持的 4–15 秒范围内：

json
{
  "error": {
    "message": "hailuo-video-3.0-i2v 的 seconds 必须为 4–15 的整数，当前值为 1。",
    "type": "invalid_request_error",
    "param": "seconds",
    "code": "invalid_video_duration"
  }
}
  • 提交接口返回 4xx 时，先检查模型 ID、必填字段、时长、尺寸和参考图片格式。
  • 提交接口没有返回视频 ID 时，不要开始轮询。
  • 网络中断后可先根据已经保存的视频 ID 查询状态，避免重复提交和重复计费。
  • 任务返回 failed 时，以响应中的 error.message 为准；如需重新生成，应创建新任务。

OpenAI-compatible API gateway

SpeedyRPM