Esta página todavía está disponible solo en chino. La navegación y los menús ya aparecen en español.

创建视频生成任务

如需引用文件，先通过 文件 API 上传素材，再使用返回的 file_id。网关负责转换，服务商是否接受由上游返回结果。

素材可以使用 input_references: [{"type":"image","role":"reference","source":{"type":"file","file_id":"..."}}]。type 必须匹配实际素材的 image/audio/video 类型。网关将 source 转为 COS 签名 URL，保留 role 后执行 DSL；其他必填字段保持不变。图片和语音接口的 input_references 属于 InOneAPI 扩展。

统一入口 POST /v1/videos。返回异步任务 ID 后查询结果。以下示例展示全部公共字段，不代表一个模型同时支持全部输入方式；调用前应根据模型能力删除不支持的可选字段。

最小请求

先将 YOUR_MODEL_ID 替换为模型详情页的完整 ID，不要自行添加服务商前缀。可选参数与音色按所选模型能力填写；应用请求头默认注释。

# -H "X-APP-NAME: Your App Name"
# -H "X-APP-URL: https://your-app.example.com"
curl "https://api.inoneapi.com/v1/videos" \
  -H "Authorization: Bearer $INONEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "YOUR_MODEL_ID",
  "prompt": "A white cat running beside the sea"
}'

认证与请求头

所有请求使用服务端保存的 API Key。Authorization: Bearer ... 必填；JSON 请求使用 Content-Type: application/json。响应头 X-Gateway-Trace-ID 用于排查请求，不是任务 ID。不要把密钥放入前端代码。

完整请求示例

curl --request POST 'https://api.inoneapi.com/v1/videos' \
  --header "Authorization: Bearer $INONEAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "model": "YOUR_MODEL_ID",
  "prompt": "A white cat running beside the sea",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "input_references": [
    {
      "type": "image",
      "role": "first_frame",
      "source": {
        "type": "url",
        "url": "https://example.com/start.png"
      }
    }
  ],
  "options": {
    "seed": 42,
    "negative_prompt": "blur",
    "generate_audio": true
  },
  "callback_url": "https://example.com/webhook"
}'

参数说明

参数类型参数说明
modelstringInOneAPI 公共模型 ID，必填；不是服务商内部模型名称。
promptstring必填内容描述：主体、动作、场景、镜头、光线和风格。长度限制由模型决定。
durationinteger可选整数，单位为秒；不是毫秒。允许值由模型决定，省略时使用上游默认值。
resolutionstring可选输出分辨率，如 720p、1080p；与比例、时长组合是否可用由模型决定。
aspect_ratiostring可选宽高比，如 16:9、9:16、1:1；不是像素尺寸。
input_referencesarray可选媒体引用数组。数组顺序保留，数量和混用限制由模型决定。
input_references[].typestring每个引用必填：image、video 或 audio。
input_references[].rolestring每个引用必填：first_frame 首帧、last_frame 尾帧、reference 参考素材、speech 语音。模型不一定支持所有角色。
input_references[].sourceobject每个引用必填，包含来源类型和对应值。
input_references[].source.typestringurl、file（兼容别名 file_id）或 data。一个 source 只指定一种来源。
input_references[].source.urlstringtype=url 时必填。服务商能够访问的 HTTPS URL；签名 URL 的有效期需覆盖任务读取时间。
input_references[].source.file_idstringtype=file 或 file_id 时必填。通过 InOneAPI 文件 API 上传、属于当前 Key 的平台 ID；网关转换为 COS 签名 URL，不接受服务商文件 ID。
input_references[].source.datastringtype=data 时必填。模型接受的 Base64 或 data URL；格式、大小由服务商决定。网关不转码。
optionsobject可选对象，服务商扩展选项。例如 seed、negative_prompt、audio 开关并非统一字段；只有映射明确支持时才传入。
callback_urlstring可选 HTTPS 回调地址，仅在服务商支持并且 DSL 已映射时可用。网关不会主动发送回调，也不保证签名或重试。

媒体、扩展参数与能力限制

不要把示例中的 options 当作所有模型都支持的参数。URL、file_id、data 是互斥来源；示例中的每个引用只展示一种来源。仅文生视频时可以完全省略 input_references。图生视频传 first_frame；首尾帧生成同时传 first_frame/last_frame；参考视频和语音生成需模型单独支持。DSL 的 media_source 只提取值，不上传文件、不下载 URL、不检查媒体尺寸。公开请求不是任意供应商选项的自动兼容层。

响应与错误处理

新任务的 id 由网关封装为 ioa_v1. 开头的签名句柄，绑定用户、公共模型、创建映射和上游凭据。下方是示意值，实际使用必须完整保存返回的 ID；查询时仍提供创建时的 model。

{"id":"ioa_v1.REPLACE_WITH_RETURNED_TASK_ID","status":"queued","created_at":"2026-09-05T08:30:00Z"}

成功响应的 id、status、created_at 需要映射配置归一化；上游缺失的时间不会自动生成。创建时可能已经进入 running，不应只接受 queued。状态值必须依据真实服务商响应映射。HTTP 非 2xx 是请求失败，不等同于任务状态 failed。网络超时后创建是否成功可能未知，不要盲目重发产生重复计费；当前没有通用幂等保证。

GET /v1/videos/{id}

Crear una tarea de generación de video · Documentación · InOneAPI