视频 API 指南

视频生成采用异步任务：提交提示词和可选参考素材，保存任务 ID，定期查询状态，成功后下载视频。HTTP 200 只说明请求成功，不代表视频已经生成。

准备与参数选择

选择具有视频 API 映射的公共模型，替换 YOUR_MODEL_ID。示例 Key 来自服务端 INONEAPI_API_KEY。先用纯文本最小请求确认可用，再添加模型支持的参数。

参数含义
model、prompt必填公共模型 ID 和场景描述；建议包含主体、动作、镜头和光线。
duration可选整数秒，允许值取决于模型。
resolution如 720p/1080p，必须由所选模型支持。
aspect_ratio如 16:9/9:16，不是像素尺寸。
input_references可选 image/video/audio 引用及其角色。
options只传映射明确支持的扩展；seed、负面提示词等不是通用保证。
callback_url仅在服务商支持且映射已配置时使用，网关不主动发送回调。

创建任务并轮询

下面的 Node.js 20+ 示例先创建任务，然后每 3 秒查询，最长等待 10 分钟。生产环境应持久化完整任务 ID 和模型 ID。重新运行时可设置 INONEAPI_VIDEO_TASK_ID 继续查询，避免再次创建；模型也必须保持为创建时的值。

curl  https://api.inoneapi.com/v1/videos \
  -H "Authorization: Bearer $INONEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL_ID","prompt":"A slow camera movement across a sunlit modern library"}'

示例遇到非 2xx 会停止并保留已输出的任务 ID，不会自动重新创建。对查询的 429 可按 Retry-After 等待，对暂时性 5xx 做有限退避，然后继续查询同一 ID。总超时应根据模型耗时调整。

理解任务状态

status含义客户端动作
queued排队等待后继续查询。
running生成中等待后继续查询。
succeeded完成检查 video_url 并及时保存。
failed生成失败停止轮询，记录 error。
cancelled已取消停止轮询；不代表平台提供取消 API。
expired已过期停止轮询。

状态由服务商映射归一化，不能假设创建后一定先是 queued。未知状态应作为协议问题处理，不能无限等待。created_at、completed_at 在已映射时为 ISO 8601 字符串，不能按 Unix 秒解析。

图生视频与参考素材

先通过文件接口上传首帧图片，并用同一 Key 提交下列请求。尺寸、时长、角色只是示例，必须改为所选模型支持的组合：

{
  "model": "YOUR_MODEL_ID",
  "prompt": "Slowly move the camera forward while preserving the reference scene.",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "input_references": [
    {
      "type": "image",
      "role": "first_frame",
      "source": {
        "type": "file",
        "file_id": "file_ioa_0123456789abcdef0123456789abcdef"
      }
    }
  ]
}

首帧使用 first_frame，尾帧使用 last_frame；参考素材可用 reference，语音可用 speech，均需模型支持。source 只选一种来源：file（别名 file_id）、url 或 data。文件 ID 由网关展开为私有 COS 签名 URL；不会自动转码或验证上游是否接受该角色。

公共文件保存按 COS 1 天生命周期处理，签名 URL 有效 5 分钟。服务商必须在有效期内读取；任务尚未读取素材前不要主动删除文件。

任务 ID、权限与查询路由

新创建任务返回以 ioa_v1. 开头的签名句柄，将它当作不透明字符串原样保存并 URL 编码，不要自行解析、截断或替换成上游 ID。查询必须带与创建相同的 model，并使用同一用户所有、具备该模型权限的有效 Key；包含文件的创建请求还需使用上传文件的 Key。

句柄绑定创建时的映射与上游凭据，以及用户和公共模型。查询会回到该映射与凭据；若其已不可用，不会自动换到其他服务商查询。无效签名、用户或模型不匹配返回 VIDEO_TASK_NOT_FOUND。旧版原始任务 ID 不具有同等绑定保证，迁移时需保持原有上游配置。

结果保存与异常恢复

成功后的 video_url 由服务商提供，可能过期，不是永久托管承诺。及时保存到业务存储；外部下载不要附带 InOneAPI Key，浏览器保留直接下载链接。

创建请求超时后任务可能已经启动，没有通用幂等保证；不要因查询失败再次 POST。停止本地等待不等于取消任务。保存模型、任务 ID 和 X-Gateway-Trace-ID 以便恢复。

401/403 检查 Key 权限；404 检查句柄、所属用户、模型及上游任务；503 检查创建所用映射或凭据是否可用。网关不提供统一的取消、视频文件下载代理、回调签名或回调重试服务。

POST /v1/videos · GET /v1/videos/{id} · POST /v1/files

视频 · 文档 · InOneAPI