# AI 模型调用

- API 版本：1.10.0
- 最后更新：2026-09-29
- 服务地址：`https://api.ailingtu.com`
- 网页文档：[AI 模型调用](/openapi/ai-model-api)
- 完整接口约束：[JSON Schema](/openapi/operations/createRelayChatCompletion.json)
- 接口发现：[接口索引](/openapi/operations/index.json)

## POST /v1/relay/chat/completions

接口标识：`createRelayChatCompletion`

通过统一的 OpenAI 兼容接口调用灵途支持的文本与视觉模型，支持普通 JSON 和 SSE 流式响应。

鉴权：请求头 `x-api-key: <YOUR_API_KEY>`；密钥仅保存在服务端。

成功判断：非流式响应读取 choices；流式响应拼接 choices[0].delta.content，收到 data: [DONE] 后结束；同时检查 HTTP 状态。

### 请求参数

| 字段 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `model` | body | string | 是 | 要调用的模型标识，必须是当前账号可用的受支持模型 |
| `messages` | body | RelayChatMessage[] | 是 | OpenAI 兼容的对话消息，支持文本及受支持的 image_url 内容 |
| `stream` | body | boolean | 否 | 为 true 时返回 SSE 增量内容；默认为 false |
| `max_tokens` | body | integer | 否 | 最大输出 token 数 |
| `thinking.type` | body | enabled \| disabled | 否 | 在模型支持时启用或关闭思考模式 |

请求格式：`application/json`

### 流式事件：增量模型输出

```json
{
  "id": "chatcmpl_2066122904659169280",
  "model": "deepseek-v4-flash-vision-exp",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "请求已"
      },
      "finish_reason": null
    }
  ]
}
```

### 响应字段

以下列出主要层级；完整结构、联合类型及校验规则以接口 JSON Schema 为准。必填指字段所在对象中的约束。

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 否 | — |
| `model` | string | 否 | — |
| `choices` | object[] | 是 | — |
| `choices[].index` | integer | 是 | — |
| `choices[].message` | object | 是 | — |
| `choices[].message.role` | string | 是 | 固定值：assistant |
| `choices[].message.content` | string | 是 | — |
| `choices[].finish_reason` | string \| null | 否 | — |
| `choices[].delta` | object | 是 | — |
| `choices[].delta.content` | string | 否 | — |

### 接入说明与限制

- 密钥只能保存在服务端，不要把 x-api-key 写入浏览器代码、日志或公开文件。
- stream=true 时逐条解析 data: 行，拼接 choices[0].delta.content；收到 data: [DONE] 后结束。
- 算力消耗取决于所选模型、输入内容、输出长度以及是否包含图片等多模态内容。
- image_url 必须是模型服务可访问的 URL，并根据业务需要选择合适的 detail。

### 错误处理

| HTTP | 说明 |
|---|---|
| 400 | 请求参数或请求体无效，请修正后重试。 |
| 401 | API 密钥缺失或无效，请检查 x-api-key。 |
| 403 | API 密钥没有此接口的调用权限。 |
| 429 | 请求过于频繁，请采用指数退避重试。 |
| 500 | 服务端发生错误；对于暂时性故障采用指数退避重试。 |

业务 code 非零时也应按失败处理。不要对参数、权限或授权错误盲目重试。创建发布或生成任务超时后先查询原任务，避免重复创建。