图片、视频与音频

视频接口：提交、查询与下载

使用归壹统一异步任务接口，分清 Sora、可灵、即梦与通用视频格式。

约 10 分钟阅读·面向开发者

视频通常是异步任务：先提交一次，再使用返回的任务 ID 查询，成功后下载。不要为了查进度重复提交生成请求。HTTP 提交成功只表示请求被接收，不表示已经出片。

归壹统一任务接口#

阶段	方法与归壹地址	说明
提交	POST https://univto.com/v1/videos	执行会产生生成任务及相应预扣或费用
查询	GET https://univto.com/v1/videos/{task_id}	填写归壹本次实际返回的 ID，不使用上游 ID
内容	GET https://univto.com/v1/videos/{task_id}/content	任务成功后使用；实际提供能力以型号和线路为准

这三个阶段均使用 Authorization: Bearer <你的归壹 API 密钥>。以下 JSON 示例对应已有归壹映射的 Seedance／cdance 类线路。其他型号是否支持 JSON、multipart、参考图片或音频，必须单独确认，不能只看路径相同。

提交参数#

字段	在本页示例中的用法
model	必填；当前账号有权使用的完整视频模型 ID
prompt	必填；描述画面、动作与镜头
seconds / duration	视频秒数；示例使用 seconds=5，不混填互相矛盾的值
size / resolution	分辨率含义因协议而异；Seedance 类示例使用 480p 档位，不应当成 480×480 像素
metadata	部分映射使用的可选参数对象；本页只设置 resolution 与 generate_audio
参考素材	图片、视频和音频参考的字段及支持数量需按型号确认，不能跨格式直接复用

统一接口提交模板；替换为当前可用型号后执行会产生费用

# 先在本地安全设置 UNIVTO_API_KEY。
curl --fail-with-body 'https://univto.com/v1/videos' \
  -H "Authorization: Bearer $UNIVTO_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"model":"替换为当前可用的cdance或Seedance模型ID","prompt":"白色桌面上一只蓝色纸鹤缓缓旋转，镜头固定","seconds":5,"size":"480p","metadata":{"resolution":"480p","generate_audio":false}}'

用真实任务 ID 查询和下载#

把任务 ID 替换为上一步真实返回的归壹 ID，不要使用文档里的虚构编号

# TASK_ID 设置为提交响应中真实返回的归壹任务 ID。
curl --fail-with-body "https://univto.com/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $UNIVTO_API_KEY"

# 仅在任务已成功、且该线路支持内容接口时下载。
curl --fail "https://univto.com/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $UNIVTO_API_KEY" \
  --output result.mp4

提交响应中的 id 或任务字段用于后续查询。按实际 status 判断排队、处理中、成功或失败；常见公开状态包括 queued、in_progress、completed、failed，但不要将未知状态当作成功。下载接口返回二进制媒体，先检查 HTTP 状态和 Content-Type，避免把错误 JSON 保存成 MP4。查询应设置间隔、总超时和退避，遵守 Retry-After。

各种视频格式有什么不同#

格式	对照协议路径	与归壹的关系
OpenAI / Sora	POST /v1/videos；GET /v1/videos/{id}；GET /v1/videos/{id}/content	归壹使用相同形状的统一客户接口，但每个模型支持的请求体不同
通用视频生成格式	POST /v1/video/generations；GET /v1/video/generations/{task_id}	这是另一套提交与查询合同；归壹已接入的相关型号经统一 /v1/videos 调用，不能仅改域名后使用此路径
可灵文生视频	POST /kling/v1/videos/text2video；GET 对应路径/{task_id}	仅协议参考，未在此确认归壹开放这些原生路径
可灵图生视频	POST /kling/v1/videos/image2video；GET 对应路径/{task_id}	仅协议参考；参考图片和文生视频字段不能混同
即梦原生视频	POST /jimeng/，以 Action 与 Version 查询参数选择操作	仅协议参考，不能把它与 Seedance 的统一路径视为同一个接口

OpenAI / Sora 的字段参考#

Sora 风格创建接口常使用 multipart/form-data：model、prompt、seconds，以及可选 input_reference 图片文件。返回对象可包含 id、model、status、progress、seconds、size 等，再按 ID 查询和下载。归壹的其他任务映射即使使用同一 /v1/videos 路径，也可能只接收 JSON，不能默认支持 Sora 的文件上传字段。

Sora multipart 字段示意（协议参考，未承诺此型号在归壹开放）

POST /v1/videos
Authorization: Bearer <你的归壹 API 密钥>
Content-Type: multipart/form-data（由客户端生成 boundary）

model = <已确认支持 Sora 格式的模型 ID>
prompt = 一只蓝色纸鹤在桌面上缓缓旋转
seconds = 8
input_reference = <可选的本地参考图片文件>

通用视频生成格式的字段参考#

通用格式将 model、prompt、image、duration、width、height、fps、seed、n 与扩展参数放在 JSON 中；image 为可选图片引用。提交可能返回 task_id 与 status，查询再返回状态、结果地址或错误。哪些字段必需、时长与尺寸可选什么，仍须按具体型号检查。归壹现有此类映射以 /v1/videos 为客户入口，不向客户要求其他服务商的凭据。

通用视频生成协议的最小请求体示意，不是归壹原生路径调用教程

{
  "model": "替换为支持该协议的模型ID",
  "prompt": "蓝色纸鹤缓缓转动，固定镜头",
  "duration": 5
}

可灵：文生视频和图生视频#

可灵文生视频参考路径为 /kling/v1/videos/text2video，图生视频为 /kling/v1/videos/image2video。两者分别在自己的路径后追加 /{task_id} 查询，不能拿文生视频 ID 到图生视频查询接口。参考请求用 model、prompt、duration；图生视频再提供 image。这里记录的是协议参考，不代表归壹已直接开放 /kling 路径。

可灵文生视频请求体（协议参考）

{
  "model": "kling-v1",
  "prompt": "蓝色纸鹤在桌面上缓缓转动",
  "duration": 5
}

可灵图生视频请求体（协议参考；替换图片地址）

{
  "model": "kling-v1",
  "image": "https://example.com/your-image.png",
  "prompt": "保持纸鹤形状，让它缓缓转动",
  "duration": 5
}

即梦：Action 选择提交或查询#

即梦参考格式使用 /jimeng/?Action=CVSync2AsyncSubmitTask&Version=2022-08-31 提交，Action=CVSync2AsyncGetResult 用于取结果。JSON 可包含 req_key、prompt、binary_data_base64。req_key 对应具体产品能力，不能根据模型昵称猜测；查询所需的任务字段应遵循该产品合同。此原生路径尚未在归壹完成验收，不提供换域后即可执行的示例。

即梦提交请求体结构（协议参考）

{
  "req_key": "jimeng_video_generation",
  "prompt": "蓝色纸鹤在桌面上缓缓转动"
}

即梦原生响应可能使用 code、message、data 表达业务结果；这和统一接口的 status 不是同一层含义。HTTP 200、业务处理成功、任务生成完成是三个不同判断，接入时都需要处理。