深圳市专企云算科技有限公司 API 文档
    • 平台介绍
    • 快速开始
    • 模型列表与选择
    • 国内模型接入方式
    • 错误处理
    • 视频与异步任务说明
    • 模型
      • 获取可用模型
        GET
    • 文本与多模态
      • 创建对话响应
        POST
    • 向量
      • 创建文本向量
        POST
    • 重排序
      • 重排序候选文档
        POST
    • 图片
      • 生成图片
        POST
    • 音频
      • 创建语音
        POST
      • 创建语音转写
        POST
    • 视频
      • 创建视频任务
        POST
      • 查询视频状态和实际Tokens
        GET
      • 下载已成功的视频
        GET
    • 数据模型
      • ErrorResponse
      • ZQVideoTaskEnvelope
      • Model
      • ZQVideoUsage
      • ModelList
      • ZQVideoAPIError
      • ChatContentPart
      • ZQVideoCreateVideoRequest
      • ChatMessage
      • ZQVideoTask
      • ChatCompletionRequest
      • ZQVideoCreatedVideo
      • Usage
      • ZQVideoContentItem
      • ChatChoice
      • ZQVideoVideoOptions
      • ChatCompletionResponse
      • EmbeddingRequest
      • EmbeddingData
      • EmbeddingResponse
      • RerankRequest
      • RerankResult
      • RerankResponse
      • ImageGenerationRequest
      • ImageData
      • ImageGenerationResponse
      • SpeechRequest
      • TranscriptionRequest
      • TranscriptionResponse

    视频与异步任务说明

    文档版本:2026-10-27 · 通用视频协议
    本页集中维护专企云算的通用异步视频接口。模型通过 model 选择;支持本协议的模型共用创建、查询、下载流程。支持本协议的模型统一使用平台地址和公开模型名;调用时使用已获目标模型授权的 API Key,具体权限按所选分组和 Key 设置确定。
    统一接口不代表所有模型具有相同能力。时长、分辨率、参考素材和扩展参数按本页的“模型差异与验证范围”使用。只有完成本协议适配的模型才适用本页;不能把其他视频协议直接套入。
    本页适用于已经完成此通用协议适配且对当前 Key 开放的接入方案。artsdance-2-0-pro、doubao-seedance-2.5 的基础示例保留供理解协议;同名模型也可能因接入方案而有不同参数要求,不能仅凭名称照搬素材开关或能力。模型是否开放,以 GET /v1/models 和账号授权为准;具体可选参数、默认值及素材能力以你收到的对应接入指南为准。

    1. 服务范围与协议#

    服务地址:https://zhuanqicloud.com。
    功能方法与路径当前状态
    查看本 Key 可用模型GET /v1/models已核验
    创建视频任务POST /v1/video/generations两个模型均有成功记录
    查询单个任务GET /v1/video/generations/{task_id}两个模型均已只读核验
    下载视频GET /v1/videos/{task_id}/content两个模型均有下载成功记录
    其他服务协议的原生任务路径—不属于本页通用协议,不能直接套用其他服务的任务 SDK
    参考素材自动处理随 POST /v1/video/generations 提交doubao-seedance-2.5 支持图片、视频和音频参考;平台随任务自动处理,客户无需单独执行入库操作,详见第 5 节
    任务取消/删除、生成回调、幂等键、批量任务列表—不在本页保证范围内
    每个 API Key 的可用模型由创建时所选分组、账号授权和 Key 的模型限制共同决定。请在获授权且包含目标模型的分组下创建 Key,再通过请求中的 model 选择模型。只有同一个 Key 实际具备多个模型的调用权限时,才能共用该 Key;模型分属不同分组且当前 Key 未覆盖目标模型时,应使用对应分组的 Key,不能仅修改 model 跨分组调用。调用前以该 Key 的 GET /v1/models 返回核对可用模型。
    不要混用 /v1/video/generations/{task_id} 与 /v1/videos/{task_id} 的查询响应解析方式。本页统一使用前者查询、后者的 /content 子路径下载。

    2. 鉴权#

    所有上述接口都携带:
    创建任务还需 Content-Type: application/json。Key 在客户自己的服务端配置,不放进前端网页、公开仓库或第三方视频下载请求。
    下列 curl 示例适用于 Bash/zsh。环境变量 ZHUANQI_API_KEY 由客户自行设置。

    3. 最小文生视频请求#

    {
      "model": "artsdance-2-0-pro",
      "prompt": "清晨的海边,波浪轻柔拍打沙滩,写实电影感,无字幕。",
      "duration": 5,
      "metadata": {
        "resolution": "720p",
        "ratio": "16:9",
        "generate_audio": false
      }
    }
    调用 doubao-seedance-2.5 时,将 model 设为该名称,并使用其所属分组下具备该模型权限的 Key。本例基础参数可沿用;其他模型应按各自参数要求填写。
    以下命令创建一条视频任务,模型通过 model 指定:
    不要给创建命令添加自动重试。创建超时可能已经生成任务,应先核对任务记录。

    4. 请求参数#

    4.1 通用字段及兼容写法#

    字段类型要求与含义
    modelstring必填;当前 Key 可用且兼容本协议的公开模型名
    promptstring简单文生视频的非空提示词;使用 content 时,可由其中的文本项提供
    contentarray参考素材请求放在顶层;至少含一项非空文本。不要只传媒体、不传文字
    durationinteger推荐显式填写方案允许的正整数秒,基础推荐值 5。本文 Artsdance 方案省略时采用10秒;其他方案的默认值与范围按对应指南,不把某一模型范围推广到全部模型
    return_last_frameboolean在已开通尾帧能力的方案中,true请求输出生成视频的尾帧。本文 Artsdance 方案与既有2.5示例均已接入;可放顶层或metadata,顶层优先,必须是JSON布尔值。不同查询响应的读取方式见第7.1节
    resolutionstring是否可省略及默认档位按对应接入方案;本文 Artsdance 方案与既有2.5示例均可省略并默认720p。可放顶层或metadata.resolution,顶层优先;显式空值不等于省略,无效档位会报错。不将该默认值推广到其他模型
    ratiostring画面比例,可放顶层或 metadata.ratio;推荐明确填写 16:9
    generate_audioboolean是否生成音轨,可放顶层或 metadata.generate_audio;文生视频验收基线为 false,有声参考场景见第 5 节
    metadataobject兼容容器,支持字段按接入方案。本文 Artsdance 方案包含duration、resolution、ratio、seed、watermark、generate_audio、return_last_frame;相同字段顶层优先,保留显式false和seed:0。不能据此假定其他方案兼容全部字段
    assetbooleandoubao-seedance-2.5 的媒体处理开关,媒体示例为 true;保持顶层。它不是素材 ID,也不代表已完成真人授权
    width / heightinteger兼容字段会被忽略;实际尺寸由分辨率、比例及编码对齐决定
    有 content 时,提示词取自其中的文本项;不要只保留媒体项,再期待顶层 prompt 自动补入。建议只选择一种提示词写法,避免相互冲突。
    通用示例可使用第3节的prompt兼容写法;支持参考输入的方案将content放顶层。实际可用参数以对应接入指南为准,不把metadata.content视为通用写法,也不要把某一方案的素材开关套用于其他方案。

    4.2 模型差异与验证范围#

    模型当前接入认可的分辨率档位已验证推荐基线
    artsdance-2-0-pro480p、720p、1080p、4k5 秒、720p、16:9、无音轨
    doubao-seedance-2.5480p、720p、1080p5 秒、720p、16:9、无音轨;另有 4 秒/480p 成功记录
    档位被接入层认可,不代表所有输入和参数组合都完成生成验收。首次接入使用推荐基线。
    能力artsdance-2-0-prodoubao-seedance-2.5
    文生视频、查询、下载已验证已验证
    参考图片尚未完成本页生成验收已验证:4秒 / 480p,完成生成、查询和下载
    参考视频尚未完成本页生成验收已验证:4秒 / 480p,完成生成、查询和下载
    参考音频尚未完成本页生成验收已验证:4秒 / 480p,完成生成、查询和下载;成片已检出音轨
    asset 开关不沿用另一模型的媒体开关参考素材显式传 true,省略按 false
    提示词prompt 或含非空文本项的顶层 content同左;有 content 时以其中的文本为准
    自动时长 duration:-1当前不支持当前不支持
    首尾帧输入、编辑、延长本页未完成验收本页未完成验收,不能套用参考素材示例直接承诺可用
    参考素材“已验证”只代表对应最小场景完成生成、查询和下载,不保证任意素材组合、最大数量或真人授权场景。各场景的结果单独记录,不相互代替。
    当前不要使用 duration:-1(自动时长),接入校验会拒绝。不要将其他协议的 seconds、size 或 multipart 上传示例套入本接口。
    frames、fps、camera_fixed、output_format、draft、tools、service_tier、priority、callback_url等扩展项不作为所有模型的通用能力承诺;字段可提交不代表实际效果已验证。seed和watermark仅按对应接入指南使用,不从同名模型推断完整范围或重复生成效果。既有2.5文生视频基线不携带camera_fixed。

    5. 图片、视频和音频参考#

    本节保留特定已开通2.5方案的参考素材示例,不是所有同名模型或Key的通用参数要求;其他方案请使用其对应接入指南。本文Artsdance方案直接使用其已接入的HTTPS URL参考结构,不要求沿用本节的asset:true。以下“随任务提交、自动处理”的说明仅适用于本节对应的2.5方案。调用 doubao-seedance-2.5 时,将可直接读取的 HTTPS 图片、视频或音频链接放入生成请求,平台自动完成本次任务所需的素材处理,客户无需先单独上传入库或取得素材 ID。重复使用同一素材时,在新任务中再次提交有效链接即可;请自行保存原文件,并确保链接在素材读取期间可访问。其他模型按各自已说明的参考素材能力使用。
    使用 doubao-seedance-2.5 的图片、视频或音频参考时,在请求最外层明确填写 asset:true,并在 content 中提供文字和素材链接,具体写法见以下示例。该字段开启本次任务的素材处理,不是素材 ID 或真人授权凭证;跨任务复用请继续提供原素材的有效链接。

    5.1 素材字段#

    用途type文件链接字段role
    参考图片image_urlimage_url.urlreference_image
    参考视频video_urlvideo_url.urlreference_video
    参考音频audio_urlaudio_url.urlreference_audio
    首帧图片(未验收)image_urlimage_url.urlfirst_frame
    尾帧图片(未验收)image_urlimage_url.urllast_frame
    每个素材一项对象;多素材继续添加对象。content 中必须保留非空 text 项;顶层 prompt 不会自动补进已有的 content。不要混合首尾帧角色与 reference_* 角色。单次生成的具体多素材组合仍需单独验收。

    5.2 参考图片请求#

    验证状态:已验证:4秒 / 480p,完成生成、查询和下载。下面使用占位链接,替换成你有权使用的真实文件链接后再提交。
    发送到 POST https://zhuanqicloud.com/v1/video/generations,使用第 2 节的平台鉴权。
    {
      "model": "doubao-seedance-2.5",
      "asset": true,
      "content": [
        {
          "type": "text",
          "text": "Use the reference image to show a bumblebee gently moving on a flower. Natural daylight, no text."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/reference.png"
          },
          "role": "reference_image"
        }
      ],
      "duration": 4,
      "resolution": "480p",
      "ratio": "16:9",
      "generate_audio": false
    }

    5.3 参考视频请求#

    验证状态:已验证:4秒 / 480p,完成生成、查询和下载。下列链接为占位符。
    发送到 POST https://zhuanqicloud.com/v1/video/generations,使用第 2 节的平台鉴权。
    {
      "model": "doubao-seedance-2.5",
      "asset": true,
      "content": [
        {
          "type": "text",
          "text": "Create a new peaceful nature shot inspired by the reference video scenery and camera movement. No text."
        },
        {
          "type": "video_url",
          "video_url": {
            "url": "https://example.com/reference.mp4"
          },
          "role": "reference_video"
        }
      ],
      "duration": 4,
      "resolution": "480p",
      "ratio": "16:9",
      "generate_audio": false
    }

    5.4 参考音频请求#

    验证状态:已验证:4秒 / 480p,完成生成、查询和下载;成片已检出音轨。下列链接为占位符。
    发送到 POST https://zhuanqicloud.com/v1/video/generations,使用第 2 节的平台鉴权。
    {
      "model": "doubao-seedance-2.5",
      "asset": true,
      "content": [
        {
          "type": "text",
          "text": "Create a colorful abstract animation synchronized to the rhythm of the reference music. No people or text."
        },
        {
          "type": "audio_url",
          "audio_url": {
            "url": "https://example.com/reference.mp3"
          },
          "role": "reference_audio"
        }
      ],
      "duration": 4,
      "resolution": "480p",
      "ratio": "16:9",
      "generate_audio": true
    }
    音频参考示例包含文字与音频,没有图片或视频;是否通过实际验收以上方状态为准。其他示例设置 generate_audio:false;有声生成不能只根据上传了音频就推断成功,应检查成片是否含音轨。

    5.5 素材格式与使用边界#

    下面是 doubao-seedance-2.5 媒体输入的文档约束,数量和大小上限尚未逐项做边界生成测试;首次接入从单份素材开始。
    素材格式及限制
    图片JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC、HEIF;单张小于30MB;单边300~6000像素,宽高比0.4~2.5;参考模式最多30张
    视频MP4/MOV;单份不超过200MB;24~60fps;单边300~6000像素,宽高比0.4~2.5,总像素407696~8295044;单段2~30秒、合计不超过30秒;最多10份
    音频WAV/MP3;单份不超过15MB;单段2~30秒、合计不超过30秒;最多10份
    使用公网可读的文件直链;不要提交本地路径、需要登录的页面或普通网盘分享页。链接的有效时间应覆盖素材读取阶段。图片/音频 Base64 以及 asset:// ID 尚未纳入本页稳定示例;视频不要使用 Base64。
    首尾帧输入场景涉及 ratio:adaptive,尚未完成本页验收。视频编辑需要的自动时长 duration:-1 当前会被平台拒绝,因此本页不把编辑、延长和完整官方协议列为已开放功能。

    5.6 素材复用与真人授权#

    请确保有权使用所提交的素材,并满足对应模型的真人认证、授权与内容审核要求。asset:true 不表示免审核,也不保证任意真人照片可直接生成。
    参考素材自动处理服务于当前生成任务,与长期素材库管理属于不同的使用流程。需要长期保存、素材列表或删除、集中真人授权管理时,请联系技术支持,确认适用模型、账号权限和具体支持范围后再接入。素材复用优先使用自己保存的原文件链接;不要将任务 ID 当作素材 ID,也不要直接套用其他账号或平台的 asset:// 标识。

    6. 创建响应与平台任务 ID#

    HTTP 200 的创建成功响应是顶层任务对象,示例为结构说明:
    {
      "id": "task_EXAMPLE",
      "task_id": "task_EXAMPLE",
      "object": "video",
      "model": "artsdance-2-0-pro",
      "status": "queued",
      "progress": 0,
      "created_at": 1789530000
    }
    立即保存顶层 task_id,缺失时兼容读取 id。不要使用后续查询响应里的数字 data.id,也不要改用嵌套的其他任务标识。
    创建成功表示任务接受,不表示视频已生成或费用已完成结算。

    7. 查询状态与实际 Tokens#

    查询返回包装对象,与创建响应不同。以下是成功任务的精简结构;省略其他非必需字段:
    {
      "code": "success",
      "message": "",
      "data": {
        "task_id": "task_EXAMPLE",
        "status": "SUCCESS",
        "progress": "100%",
        "fail_reason": "",
        "result_url": "https://example.com/result.mp4",
        "submit_time": 1789530000,
        "start_time": 1789530020,
        "finish_time": 1789530300,
        "data": {
          "usage": {
            "completion_tokens": 108900,
            "total_tokens": 108900
          }
        }
      }
    }
    上例数值仅用于说明结构,不能作为所有任务的耗时或计费量。
    字段客户端处理
    顶层 codesuccess 表示查询操作成功,不能据此判断视频成功
    data.status业务状态判断依据,使用下表
    data.progress百分比字符串;不能当作准确剩余时间
    data.fail_reason任务失败原因
    data.result_url成功时可能返回的成片地址;优先使用平台下载接口
    data.submit_time / start_time / finish_timeUnix 秒时间戳;未发生的阶段可能是 0,不把尚未生成的时间误算为耗时
    data.data.usage.completion_tokens完成后实际返回的输出 Tokens 整数
    data.data.usage.total_tokens完成后实际返回的总 Tokens 整数
    内层 data.data 的其他字段可能随模型不同而变化。2.5 可能包含 content.video_url,Artsdance 可能使用其他嵌套结构;不要把其中一种结构套给另一个模型。
    Tokens 应原样展示整数,例如 108900 或 108,900。未提供的用量字段显示“未提供”,不能用价格反推、不能补成 0、不能把视频 Tokens 当作提示词字数。短时间内完成状态与最终账单可能存在结算先后,以最终使用记录为准。

    7.1 返回生成视频的尾帧(按接入方案)#

    已开通此能力时,创建传return_last_frame:true或metadata.return_last_frame:true,顶层优先。这是输出生成视频的尾帧,不是首尾帧参考输入,不会创建素材ID。本文Artsdance方案已接入该参数;成功后使用简洁查询GET /v1/videos/{task_id}读取metadata.last_frame_url。下面保留既有2.5的包装查询字段与示例,不能把某一嵌套结构当作所有模型的固定返回。
    任务成功后:
    GET /v1/video/generations/{task_id}:读取 data.data.content.last_frame_url。
    GET /v1/videos/{task_id}:读取 metadata.last_frame_url。
    直接下载返回链接时不要发送平台Key,保留链接签名并及时保存。图片格式以下载响应的 Content-Type 为准,不要固定按PNG解析;2026-09-21实测返回JPEG,1280×720,与视频尺寸一致。未返回链接时表示当前响应未提供尾帧,不能拿视频地址代替。
    以下请求省略resolution,2.5默认720p:
    {
      "model": "doubao-seedance-2.5",
      "prompt": "一只纸船在平静的湖面缓缓漂动,固定镜头。",
      "duration": 4,
      "ratio": "16:9",
      "generate_audio": false,
      "return_last_frame": true
    }

    8. 轮询与失败终态#

    data.status处理
    NOT_START、QUEUED、SUBMITTED等待并继续查询
    IN_PROGRESS生成中,继续查询
    SUCCESS停止轮询,下载视频
    FAILURE停止轮询,读取失败原因和最终使用记录
    其他值或缺失保存本地诊断信息,停止自动处理并联系支持
    推荐约每 20 秒查询一次,客户端总等待预算约 60 分钟。该预算不是服务端取消指令、任务完成承诺或固定限流值。达到预算后保留任务 ID,稍后继续查询原任务。
    只读查询遇到临时 429/5xx 可延迟重试,优先参考 Retry-After;401/403 应先处理 Key/分组权限。任何查询错误都不应该触发重新创建任务。
    按第 7 节的查询示例重复查询同一任务,遇到成功或失败终态即停止;成功后按第 9 节下载。达到等待预算后,仍使用原任务 ID 续查。

    9. 下载成片#

    确认状态为 SUCCESS 后:
    下载失败可以重试原任务的下载,不要重新生成。保存视频前检查 HTTP 状态和内容类型,避免把 JSON 错误当作 MP4。
    如使用任务中返回的 HTTPS 成片 URL 直接下载,不要发送平台 Key,并保留 URL 中的签名参数。地址有效期不是固定承诺,生成完成后及时保存。

    10. 错误与费用#

    视频接口可能返回:
    {"code":"invalid_resolution","message":"unsupported resolution for model","data":null}
    鉴权/路由层也可能使用 {"error":{"code":"...","message":"..."}};客户端应同时处理 HTTP 状态和两种错误包装,不依赖固定中文文案。
    情况处理
    401 / Key 无效检查 Key 是否有效、是否正确携带 Bearer
    403 / 分组、模型权限或余额问题根据实际错误检查账户、Key、允许模型和可用余额
    invalid_duration时长错误;本页当前版本不要传 -1;明确未创建时再修正提交
    invalid_resolution检查显式分辨率是否为空或不被方案接受;本文Artsdance方案与既有2.5示例省略时默认720p,其他方案按对应指南。不要把显式空值当省略
    invalid_content检查非空文本是否在正确位置、content 是否为数组
    task_not_exist检查平台任务 ID 和查询账号是否正确;不要用数字记录 ID
    429请求受限;保留任务 ID,按返回信息延迟查询;不能推断是生成失败
    5xx、断线、超时、无法解析创建响应任务可能已接受;先查任务记录,禁止自动重发创建
    接口不承诺固定 RPM/并发额度。任何具体额度应以当前账号约定及实际服务设置为准。
    任务可能先预扣额度、后按实际用量结算并调整差额。最终费用查看平台使用记录;各模型分别按自身计价规则及适用分组配置计费。包含参考视频可能影响计费分类及预扣额度,因此不能按纯文本生成费用推算。
    价格以 模型价格页 当前展示及适用账号约定为准。本页不写死折扣、退款金额或预扣倍数。

    11. 接入检查与技术支持#

    接入时核对:本 Key 能列出模型;创建后保存平台任务 ID;查询 data.status;成功后下载;读取实际 usage;超时后续查同一任务。正式使用参考素材前单独完成场景验收。
    技术支持:service@zhuanqicloud.com。排查请提供模型、任务 ID、请求时间及脱敏错误;不要提交完整 Key 或公开带签名的成片 URL。
    上一页
    错误处理
    下一页
    获取可用模型
    Built with