深圳市专企云算科技有限公司 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

    错误处理

    请同时检查 HTTP 状态码与响应正文。兼容接口的错误通常位于 error.message;视频异步接口也可能使用顶层 code、message、data 结构。具体以该接口的响应定义为准,不要仅凭 HTTP 200 判断任务已生成成功。

    常见 HTTP 状态#

    HTTP 状态码常见含义建议处理
    400参数、格式或模型能力不匹配检查接口路径、字段类型和目标模型能力
    401API Key 缺失、无效或已过期检查 Bearer 鉴权头与密钥状态
    403权限受限,或请求预扣额度不足结合错误消息检查账户分组、密钥限制、余额及预扣要求
    404接口、模型、任务或结果资源不存在检查路径、模型 ID、任务 ID 及对应账户权限
    429频率或并发限制,也可能是额度相关错误根据错误消息区分限流与额度问题;额度不足应先处理余额
    500平台或任务处理异常保存响应信息,按请求是否可能已受理决定后续处理
    502上游暂时不可用或返回异常保存响应信息;查询请求可以有限重试,提交请求先判断是否已受理
    状态码不构成所有上游错误的固定映射。同一状态下应继续读取错误消息;任务失败也可能通过正常 HTTP 响应中的失败状态返回。

    异步任务错误#

    异步流程需要分清三个结果:
    1.
    请求是否到达并被受理:检查提交响应及任务 ID。
    2.
    任务当前状态:使用查询接口读取排队、处理中、成功或失败等实际状态。
    3.
    结果是否可取得:成功后按接口定义读取结果地址或下载内容。
    使用 code、message、data 的响应时,应按具体接口说明判断业务状态;message 用于排查原因,任务和结果字段可能位于 data 中。不要把通用对话接口的 choices 解析逻辑用于视频任务。
    若返回 403 且消息明确指出预扣额度不足,请检查账户与 API Key 可用额度。预扣校验未通过不能通过重复提交解决;具体计费与结算规则以平台控制台和视频接口说明为准。

    重试与超时#

    GET 任务查询遇到临时网络错误、限流或服务异常时,可以进行有限次数重试,采用指数退避和随机抖动;若响应提供 Retry-After,优先遵循该提示。达到客户端设定的查询截止时间后停止轮询并保存任务 ID。
    POST 生成请求超时或断开连接时,服务端可能已经受理。不要自动重新提交,避免重复任务和重复计费。已经取得任务 ID 时继续查询原任务;没有任务 ID、受理状态又不明确时,先检查控制台任务记录或联系支持人员。
    除非接口明确提供并说明幂等机制,否则不要假定相同请求体会自动去重,也不要自行假设某个幂等请求头受到支持。
    参数错误、鉴权失败、权限不足、额度不足等确定性错误,应先修正原因再请求。不要仅按状态码执行无限重试。
    对话流在结束前中断时,请标记结果不完整;重新发起对话请求属于新的生成调用,可能再次产生费用。
    视频任务的轮询间隔、状态字段与结果获取流程,请查看 视频与异步任务说明。

    联系支持#

    请保留请求时间(含时区)、接口路径、模型 ID、HTTP 状态码、任务 ID 或请求 ID(如有),以及脱敏后的错误消息。不要在日志或工单中记录完整 API Key,也不要公开包含访问凭证的签名下载地址。
    客服邮箱:service@zhuanqicloud.com、zhuanqicloud@gmail.com。
    上一页
    国内模型接入方式
    下一页
    视频与异步任务说明
    Built with