应用服务端调用 API 向网易云信服务端发起的请求需遵循固定的请求结构和请求方式。

请求方式

• 通信协议：服务端 API 是简单的 HTTP/HTTPS 接口，适配各种语言。

• 请求方式：应用服务端向云信服务端发起的请求支持 POST、GET 方式。

服务地址

网易云信服务提供的服务域名为：ai.yunxinapi.com

• 网关服务内部注册的数据面路径为：/hub/vidu/v2/{action}

  例如：

  textPOST /hub/vidu/v2/text2video
  GET  /hub/vidu/v2/tasks/{task_id}/creations
  POST /hub/vidu/v2/tasks/{task_id}/cancel
  

• 公网调用采用直连网关方式，对外路径：https://ai.yunxinapi.com/hub/vidu/v2/text2video

  即，公网入口不挂额外前缀，直接使用 /hub/vidu/v2/*。

请求信息

云信服务端 API 请求结构主要由下表所示三部分组成。

组成部分	说明
URL	指向具体的业务请求，请参考各 API 文档。
Header	请求头，数据面统一使用 Bearer Key。
Body	请求体，包含 API 对应的业务参数，具体参考各 API 文档的 请求参数 小节。

请求 URL

请求 URL 路径遵循 RESTFUL 原则，围绕资源定义接口路径。

当前支持 POST、GET 操作类型的接口。

操作类型	示例操作	注意事项
POST 新增资源	生成图片。	GET 请求由于 URL 长度限制等原因，可以改为 POST 请求，详细说明见下文 查询参数。
GET 查询资源	查询生成物。	针对多个资源的查询，根据代码实现和业务需要，选择批量查询或者分页查询。

请求头

调用云信服务端 API 的请求，都需要在请求头（Header）中进行鉴权。

数据面统一使用 Bearer Key：

httpAuthorization: Bearer sk-xxxxx

常用请求头：

Header	必填	说明
Authorization	是	Bearer <sk-...>
Content-Type	POST 时是	建议固定为 application/json; charset=utf-8，避免中文 prompt 等 UTF-8 内容解析异常。

请求体

传入请求体（Body）的 具体业务参数 请参考各 API 文档。

• 网关不会重塑业务字段结构。
• 异步接口支持可选字段 callback_url。

查询参数

• 网关不定义额外公共查询参数。
• 各接口支持的查询参数以对应接口文档为准。

响应信息

调用云信服务端 API 的返回类型均为 JSON，同时进行 UTF-8 编码。

如调用成功，则返回状态码 200。如调用异常，则会返回相应的错误码。

• 异步提交成功：统一返回 200
• 同步提交成功：统一返回 200
• 查询生成物成功：返回 200
• 取消任务成功：返回 200

响应处理建议：

1. 先看 HTTP 状态码。
2. 成功时，优先使用网关返回的 task_id 作为后续查询和取消的唯一标识。
3. 失败时，按 错误码 判断错误类型。
4. 接收回调时，按 验签规范 做验签。

错误码

具体错误码和排查指引请参考 错误码。