通用约定

了解 AGTCloud API 的节点、地址、认证、内容类型、响应处理和错误恢复规则。

本页说明 AGTCloud API 各端点共同使用的调用规则。具体字段、状态和响应结构仍以对应的 API Reference 页面为准。

API 地址与 Base URL

本页使用的 API 地址为 https://api.agtcloud.cn，OpenAI 兼容 SDK 使用的 Base URL 为 https://api.agtcloud.cn/v1。

使用场景	地址组成	示例
原始 HTTP 请求	API 地址 + 完整 Endpoint Path	`https://api.agtcloud.cn` + `/v1/chat/completions`
OpenAI 兼容 SDK	Base URL + SDK 方法对应路径	`https://api.agtcloud.cn/v1`
Realtime WebSocket	WebSocket 节点 + 连接路径	`wss://api.agtcloud.cn/v1/realtime?model=MODEL_ID`

避免重复拼接 /v1

https://api.agtcloud.cn/v1 已经包含 /v1。使用兼容 SDK 时，不要再手动把 /v1 添加到 SDK 方法生成的路径中，否则请求可能变成 /v1/v1/...。

认证

大多数受保护的 API 使用 Bearer API Key：

Authorization: Bearer your-api-key

Anthropic Messages 使用专属认证 Header，并要求提供 API 版本：

x-api-key: your-api-key
anthropic-version: 2023-06-01

anthropic-beta 等可选 Header 及其他协议的认证要求，以对应 Endpoint 页面为准。

前往 API Keys 创建和管理令牌。调用时只发送 API Key，不要使用控制台密码、Cookie、管理员令牌或上游厂商 Key。

下面是一个最小 Chat Completions 请求：

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  --request POST \
  --header 'Authorization: Bearer your-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "你好"
      }
    ]
  }'

API Key 的创建、轮换和生产环境保存方式见 API Key、Base URL 与认证。

请求参数放在哪里

端点页面会按照参数所在位置分别展示字段：

参数位置	用途	示例
Path Parameters	标识具体资源或任务	`/v1/videos/{video_id}`
Query Parameters	控制筛选、变体或输出形式	`?variant=video`
Headers	传递认证和内容协商信息	`Authorization`、`x-api-key`、`Content-Type`
Request Body	传递模型、输入和生成参数	JSON 或 Multipart 表单

Path 参数需要先进行 URL 编码。可选参数没有使用时应省略，不要用空字符串代替所有可选值。

Content-Type 与数据格式

数据形式	常见 Content-Type	处理方式
JSON 请求和响应	`application/json`	序列化请求对象并解析 JSON
文件与表单上传	`multipart/form-data`	交由 HTTP 客户端生成 Multipart 边界
SSE 流	`text/event-stream`	按事件边界持续读取数据
SDP	`application/sdp`	用于部分实时连接协商
二进制文件	`video/mp4`、音频媒体类型等	读取字节流并保存或转发

使用 Multipart 时不要手动写死 boundary；应让浏览器、SDK 或 HTTP 客户端根据表单内容生成完整的 Content-Type。

模型 ID

Reference 示例中的 MODEL_ID 是占位符，需要替换为当前 API Key 可以使用的模型 ID。可以前往模型广场查找模型，也可以在 Try It 中填写 Key 后获取该 Key 返回的模型列表。

模型、协议和上游厂商是不同概念：

模型 ID 决定请求的目标模型。
Endpoint 决定客户端使用的协议和消息结构。
同一个模型可能提供多个协议入口，也可能只支持其中一部分字段。

解析响应

处理响应时，建议遵循以下顺序：

读取 HTTP 状态

先判断请求是否成功，再决定解析成功对象还是错误信息。不要只依据响应体中的某个字段判断结果。

检查 Content-Type

根据实际媒体类型选择 JSON、SSE、文本或二进制解析器。下载接口不能强制按 JSON 解析。

按具体协议读取字段

Chat 通常返回 choices，Responses、Gemini、异步任务和 WebSocket 使用不同结构。客户端不应假设所有接口共享同一种响应对象。

保存追踪信息

保存请求时间、Method、Path、模型和 HTTP 状态。响应中存在 Request ID 时一并保存，但不要记录完整 API Key 或敏感输入。

流式响应

SSE 接口会在一个 HTTP 响应中持续发送多个事件或数据块。客户端需要增量读取内容，而不是等待连接关闭后再把整个响应解析为单个 JSON 对象。

根据端点说明识别结束事件或结束标记。
分别处理内容增量、工具调用、Usage 和错误事件。
网络中断时，不要默认把已经收到的内容视为完整结果。
不同协议的流式事件结构不同，应使用当前端点的事件定义。

异步任务

视频、Midjourney 等接口通常先返回任务标识，再通过查询接口获取进度与最终结果：

提交任务 → 保存任务 ID → 查询状态 → 判断终止状态 → 读取结果

任务 ID 的字段名、状态枚举和查询路径由具体协议决定。不要在不同接口之间混用 id、task_id、video_id 或状态值。

轮询时应设置查询间隔与总超时，并在任务成功、失败或取消后停止。提交请求超时但任务可能已经创建时，应先确认任务状态，避免重复创建付费任务。

HTTP 状态与重试

以下是通用处理方向，具体错误结构以端点实际响应为准：

HTTP 状态	常见含义	建议处理
`400`	请求格式、字段或字段组合无效	修改请求后再发送
`401`	API Key 缺失、无效或认证 Header 格式错误	检查认证信息和 Key 状态
`403`	当前账户、Key 或资源权限不足	检查节点、权限和账户状态
`404`	路径、模型、任务或资源不存在	检查 URL、模型 ID 和资源 ID
`429`	请求受到频率、并发或额度限制	根据响应信息等待后有限重试
`5xx`	平台或上游服务暂时异常	使用退避策略进行有限重试

不要对所有错误无限重试。参数、认证和权限问题只有在修正后才适合重新发送；创建任务等可能产生副作用的请求，应先判断是否已经成功提交。

更完整的诊断步骤见错误与排障。

Usage、时间和扩展字段

Usage 字段是否存在以及字段名称由具体协议和模型决定，客户端应允许它为空或缺失。
时间字段可能使用 Unix 秒、Unix 毫秒或字符串时间，必须按端点 Schema 解析。
厂商扩展字段通常只对部分模型生效，不应当作所有模型的共同能力。
客户端解析响应时应允许出现新增的非关键字段，避免平台增加兼容字段后导致整体解析失败。

安全与日志

长期 API Key 应保存在可信服务端或密钥管理系统中，生产前端、桌面端和移动客户端不得内置 Key。
文档 Try It 仅用于客户主动发起的临时浏览器调试，不要在共享设备上使用长期生产 Key。
不要把 Key 写入公开代码仓库、截图、日志或工单。
排障材料应对 Prompt、文件地址、账户信息和请求响应中的敏感数据进行脱敏。
不再使用或疑似泄露的 Key 应及时禁用或删除，并更新使用它的服务。

继续阅读：API Reference · 快速开始 · 错误与排障

本页目录