# API 文档

从注册到第一次 API 调用，清晰完成接入。

---

# 快速开始：5 分钟发出第一个请求

URL: https://www.uucode.org/docs/quick-start

# 快速开始：5 分钟发出第一个请求

这份指南会带你完成从注册、创建 API Key，到成功收到第一条模型回复的完整流程。默认使用 OpenAI 兼容的 Chat Completions 接口；如果你使用其他客户端，可直接跳到 [工具接入](https://www.uucode.org/docs/tools)。

## 你需要准备什么

- 一个已经注册并登录的 UUcode 账户。
- 一个在控制台创建的 API Key。
- 模型广场中当前可用的模型 ID。
- 足够的账户余额，或管理员为账户分配的额度。

模型和价格会随站点配置变化，请始终以模型广场显示的名称和状态为准，不要长期硬编码模型列表。

## 第 1 步：注册并登录

打开站点首页完成注册和登录。如果站点启用了邀请制、邮箱验证或其他安全策略，请先按页面提示完成验证。

登录后进入控制台，确认账户状态正常，并查看可用分组、模型和剩余额度。

## 第 2 步：创建 API Key

进入控制台的 **API Key / 令牌** 页面，创建一个新的 Key。建议按应用或环境分别创建，例如开发、测试和生产各使用不同的 Key，便于单独停用和追踪用量。

> API Key 等同于账户凭证。不要提交到 Git、写入前端代码、截图或发送到公开聊天中。如果 Key 泄露，请立即删除旧 Key 并重新创建。

## 第 3 步：确认 Base URL 和模型

统一接口的根地址是：

~~~text
https://www.uucode.org/v1
~~~

请求时将 **YOUR_API_KEY** 替换为实际 Key，将 **YOUR_MODEL_ID** 替换为模型广场中的准确模型 ID。模型 ID、分组权限和计费倍率都由站点配置决定。

## 第 4 步：发送第一条非流式请求

下面的请求使用 Chat Completions 协议：

~~~bash
curl https://www.uucode.org/v1/chat/completions \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {"role": "user", "content": "你好，请用一句话介绍自己。"}
    ],
    "stream": false
  }'
~~~

成功响应通常包含 **choices** 和 **usage** 字段。保存响应中的请求标识，遇到问题时可连同模型名、时间和状态码提供给管理员，但不要提供 API Key。

## 第 5 步：开启流式输出

将请求中的 **stream** 改为 **true**，并使用 curl 的 **-N** 保持实时输出：

~~~bash
curl -N https://www.uucode.org/v1/chat/completions \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {"role": "user", "content": "请分三点介绍如何保护 API Key。"}
    ],
    "stream": true
  }'
~~~

流式响应使用 Server-Sent Events（SSE）格式，客户端应持续读取以 **data:** 开头的事件，并在收到结束标记后关闭连接。SDK 通常已经封装了 SSE 解析，不建议自行按固定字符串截断响应。

## 第 6 步：用 Python SDK 调用

OpenAI 兼容 SDK 只需要替换 API Key 和 Base URL：

~~~python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://www.uucode.org/v1",
)

response = client.chat.completions.create(
    model="YOUR_MODEL_ID",
    messages=[{"role": "user", "content": "你好"}],
)

print(response.choices[0].message.content)
~~~

## 成功检查清单

1. 请求地址包含正确的站点域名和 **/v1**。
2. 请求头使用 **Authorization: Bearer YOUR_API_KEY**。
3. JSON 中的 model 与模型广场完全一致。
4. 先用 **stream: false** 验证普通请求，再开启流式。
5. 账户有可用余额，且当前 Key 有对应模型权限。

## 下一步

- 认证方式和 Key 安全：阅读 [API Key 与认证](https://www.uucode.org/docs/authentication)。
- 接口路径、请求示例和协议选择：阅读 [API 参考](https://www.uucode.org/docs/api-reference)。
- 接入 OpenAI SDK、Claude、Gemini 或其他客户端：阅读 [工具接入](https://www.uucode.org/docs/tools)。
- 出现 401、429、402 或 5xx：阅读 [错误码与排查](https://www.uucode.org/docs/troubleshooting)。

---

# API 参考

URL: https://www.uucode.org/docs/api-reference

# API 参考

UUcode 是统一 AI 网关。客户端可以使用 OpenAI 兼容协议，也可以按需要使用 Claude Messages、Google Gemini、视频任务或其他专用格式。所有接口都需要 API Key，完整地址由 **https://www.uucode.org** 和接口路径组成。

## 通用约定

### 认证与请求头

JSON 接口通常使用：

~~~http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
~~~

文件上传接口使用 **multipart/form-data**，不要手动固定 Content-Type 的 boundary。认证细节见 [API Key 与认证](https://www.uucode.org/docs/authentication)。

### 模型和额度

请求中的 **model** 必须使用模型广场中实际可用的模型 ID。模型是否支持图片、音频、工具调用、推理、流式和视频任务，取决于当前站点的渠道配置；同一个接口不代表所有模型都支持全部字段。

请求可能先预扣额度，再在上游返回后按实际用量结算。请为 **max_tokens**、图片数量、视频时长等消耗参数设置合理值，不要提交异常大的数量。

### 常见响应状态

| 状态码 | 含义 |
| --- | --- |
| **200** | 同步接口成功，或异步任务创建成功 |
| **400** | JSON、表单或模型参数错误 |
| **401** | API Key 缺失或无效 |
| **402** | 余额或可用额度不足 |
| **403** | 账户、分组或模型权限不足 |
| **404** | 路径、模型或异步任务不存在 |
| **413** | 请求体过大 |
| **429** | 触发限流；可结合 Retry-After 重试 |
| **4xx / 5xx** | 具体原因以响应中的 error.message 和 error.code 为准 |

## 接口总览

### OpenAI 兼容格式

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | **/v1/models** | 获取当前 Key 可见的模型 |
| POST | **/v1/chat/completions** | 对话、文本和多模态对话 |
| POST | **/v1/completions** | 传统文本补全 |
| POST | **/v1/responses** | OpenAI Responses 格式、Agent 和工具调用 |
| POST | **/v1/responses/compact** | 压缩 Responses 对话上下文 |
| POST | **/v1/embeddings** | 生成文本向量 |
| POST | **/v1/moderations** | 内容审核 |
| POST | **/v1/images/generations** | 图片生成 |
| POST | **/v1/images/edits** | 图片编辑 |
| POST | **/v1/audio/transcriptions** | 音频转文字 |
| POST | **/v1/audio/translations** | 音频翻译 |
| POST | **/v1/audio/speech** | 文本转语音 |
| POST | **/v1/rerank** | 文档重排序 |
| GET | **/v1/realtime** | WebSocket 实时对话 |
| POST | **/v1/videos** | 创建视频任务 |
| GET | **/v1/videos/{task_id}** | 查询视频任务 |
| GET | **/v1/videos/{task_id}/content** | 获取已完成的视频内容 |

### 其他协议和任务格式

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | **/v1/messages** | Claude Messages 格式 |
| GET | **/v1beta/models** | Gemini 格式模型列表 |
| POST | **/v1beta/models/{model}:generateContent** | Gemini 同步生成 |
| POST | **/v1beta/models/{model}:streamGenerateContent** | Gemini 流式生成 |
| POST | **/v1/engines/{model}/embeddings** | Gemini 嵌入兼容路径 |
| POST | **/v1/video/generations** | JSON 视频生成任务 |
| GET | **/v1/video/generations/{task_id}** | 查询 JSON 视频任务 |
| POST | **/kling/v1/videos/text2video** | Kling 文生视频 |
| GET | **/kling/v1/videos/text2video/{task_id}** | 查询 Kling 文生视频任务 |
| POST | **/kling/v1/videos/image2video** | Kling 图生视频 |
| GET | **/kling/v1/videos/image2video/{task_id}** | 查询 Kling 图生视频任务 |
| POST | **/jimeng/** | 即梦视频生成，需按上游格式提交 |

## 模型列表

建议应用启动或配置变更时读取模型列表，而不是把模型名称长期写死：

~~~bash
curl https://www.uucode.org/v1/models \\
  -H "Authorization: Bearer YOUR_API_KEY"
~~~

返回结果中的 **data[].id** 就是可用于请求的模型 ID。模型列表只表示当前 Key 可发现的模型，具体能力仍以模型配置和请求结果为准。

## Chat Completions

### 非流式请求

~~~bash
curl https://www.uucode.org/v1/chat/completions \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {"role": "system", "content": "你是一个简洁的助手。"},
      {"role": "user", "content": "请介绍 UUcode 的统一网关。"}
    ],
    "temperature": 0.7,
    "stream": false
  }'
~~~

常用字段包括 **messages**、**model**、**temperature**、**top_p**、**max_tokens**、**stop**、**stream**、**tools** 和 **tool_choice**。不同模型支持的字段可能不同；如果上游不支持某个字段，网关会返回参数错误或按适配器规则转换。

### 流式请求

将 **stream** 设为 **true**。响应为 SSE 事件，客户端应持续读取 **data:** 行，直到收到结束标记：

~~~bash
curl -N https://www.uucode.org/v1/chat/completions \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "请分三段回答。"}],
    "stream": true
  }'
~~~

不要把流式响应当作一个完整 JSON 一次性解析。官方 SDK 和大多数兼容客户端已经处理了 SSE 拼接。

## Responses

Responses 格式适合多轮上下文、工具调用和推理工作流：

~~~bash
curl https://www.uucode.org/v1/responses \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "YOUR_MODEL_ID",
    "input": "请列出三个 API 安全建议。",
    "stream": false
  }'
~~~

流式 Responses 同样设置 **stream: true**。如果客户端只支持 Chat Completions，可优先使用 **/v1/chat/completions**，不要混用两种响应对象的解析逻辑。

**POST /v1/responses/compact** 用于压缩较长的 Responses 上下文。它不是普通聊天接口，提交前应确认客户端支持该协议和当前模型的上下文处理方式。

## Embeddings

将文本转换为向量，适合检索、聚类和语义相似度计算：

~~~bash
curl https://www.uucode.org/v1/embeddings \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "YOUR_EMBEDDING_MODEL",
    "input": ["第一段文本", "第二段文本"]
  }'
~~~

响应中的 **data[].embedding** 与输入顺序对应。批量输入时请控制文本数量和长度，避免超过上游上下文或请求体限制。

## 图片生成和编辑

### 图片生成

图片接口的请求字段由模型决定。通用 OpenAI 兼容模型可以使用 **prompt**、**size**、**n**、**quality** 等字段；部分 Qwen 图像模型使用 **input.messages** 和 **parameters**：

~~~bash
curl https://www.uucode.org/v1/images/generations \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "YOUR_IMAGE_MODEL",
    "prompt": "一只在雨夜街道上撑伞的橘猫",
    "size": "1024x1024",
    "n": 1
  }'
~~~

如果模型广场或模型说明要求 Qwen 风格请求，可参考以下结构：

~~~json
{
  "model": "qwen-image-plus",
  "input": {
    "messages": [
      {"role": "user", "content": [{"text": "生成一张城市夜景"}]}
    ]
  },
  "parameters": {
    "size": "1328*1328",
    "watermark": false
  }
}
~~~

### 图片编辑

**POST /v1/images/edits** 通常使用 multipart/form-data，提交图片文件、模型和编辑提示词。图片大小、格式和是否支持多图由当前模型决定。

## 音频

### 文本转语音

**POST /v1/audio/speech** 返回音频二进制内容，建议直接写入文件：

~~~bash
curl https://www.uucode.org/v1/audio/speech \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "YOUR_TTS_MODEL",
    "input": "欢迎使用 UUcode。",
    "voice": "alloy",
    "response_format": "mp3"
  }' \\
  --output output.mp3
~~~

### 音频转录和翻译

**POST /v1/audio/transcriptions** 与 **POST /v1/audio/translations** 使用 multipart/form-data，至少提交 **file** 和 **model**：

~~~bash
curl https://www.uucode.org/v1/audio/transcriptions \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -F "file=@audio.mp3" \\
  -F "model=whisper-1" \\
  -F "response_format=json"
~~~

可选字段包括 **language**、**prompt**、**temperature**、**response_format** 和时间戳粒度。请根据实际音频时长和站点限制控制文件大小。

## Rerank

重排序接口根据查询词返回文档相关性结果：

~~~bash
curl https://www.uucode.org/v1/rerank \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "YOUR_RERANK_MODEL",
    "query": "如何保护 API Key",
    "documents": ["使用环境变量", "公开分享完整密钥", "定期撤销旧 Key"],
    "top_n": 2,
    "return_documents": true
  }'
~~~

## Claude Messages

Claude 兼容格式使用 **POST /v1/messages**。除 Bearer Token 外，原生客户端通常需要 **anthropic-version**：

~~~bash
curl https://www.uucode.org/v1/messages \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "anthropic-version: 2023-06-01" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "YOUR_CLAUDE_MODEL",
    "max_tokens": 512,
    "messages": [
      {"role": "user", "content": "你好，请简要介绍自己。"}
    ],
    "stream": false
  }'
~~~

如果客户端使用 **x-api-key**，可以把同一个 API Key 放在该请求头中，但不要同时发送不同的凭证。

## Google Gemini

Gemini 原生格式使用模型名作为路径的一部分：

~~~bash
curl https://www.uucode.org/v1beta/models/YOUR_GEMINI_MODEL:generateContent \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "请介绍统一 AI 网关。"}]}
    ]
  }'
~~~

流式调用使用 **:streamGenerateContent**。Gemini 的 **contents**、**parts**、**generationConfig** 和多模态字段不要直接套用 Chat Completions 的 **messages** 结构。

## 视频任务

视频接口一般是异步的：创建任务后保存返回的任务 ID，轮询状态直到完成，再获取内容。

### OpenAI 兼容视频

**POST /v1/videos** 使用 multipart/form-data，可提交 **model**、**prompt**、**seconds** 和可选的 **input_reference** 文件：

~~~bash
curl https://www.uucode.org/v1/videos \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -F "model=YOUR_VIDEO_MODEL" \\
  -F "prompt=一只猫在海边奔跑" \\
  -F "seconds=5"
~~~

然后查询：

~~~bash
curl https://www.uucode.org/v1/videos/TASK_ID \\
  -H "Authorization: Bearer YOUR_API_KEY"
~~~

任务完成后获取视频内容：

~~~bash
curl https://www.uucode.org/v1/videos/TASK_ID/content \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  --output video.mp4
~~~

### JSON 视频和 Kling

部分视频渠道使用 JSON 任务接口：

~~~bash
curl https://www.uucode.org/v1/video/generations \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "YOUR_VIDEO_MODEL",
    "prompt": "宇航员在月球上漫步",
    "duration": 5,
    "width": 1280,
    "height": 720
  }'
~~~

Kling 使用 **/kling/v1/videos/text2video** 或 **/kling/v1/videos/image2video**，查询时将创建响应中的任务 ID 放入对应 GET 路径。异步任务不要高频轮询，建议逐步增加轮询间隔并处理失败状态。

## Realtime

**GET /v1/realtime** 是 WebSocket 接口，不是普通 HTTP JSON 请求。需要使用支持 WebSocket 的客户端，并按 Realtime 协议发送事件。模型是否支持实时语音或音频输入，以模型配置为准。

## 暂未实现的兼容接口

以下 OpenAI 兼容路径当前保留为未实现状态，调用会返回不支持错误：

- **/v1/files** 及其文件详情、内容和删除接口。
- **/v1/fine-tunes** 及微调详情、取消和事件接口。
- **/v1/images/variations**。

请不要把这些路径作为生产依赖；如果需要对应能力，请先确认站点版本和管理员配置。

## 下一步

- 快速验证请求：[快速开始：5 分钟发出第一个请求](https://www.uucode.org/docs/quick-start)
- 凭证与安全：[API Key 与认证](https://www.uucode.org/docs/authentication)
- SDK 和第三方客户端：[工具接入](https://www.uucode.org/docs/tools)
- 状态码、限流和上游错误：[错误码与排查](https://www.uucode.org/docs/troubleshooting)。

---

# 工具接入

URL: https://www.uucode.org/docs/tools

# 工具接入

只要客户端支持 OpenAI Compatible，通常只需要配置三项：Base URL、API Key 和 Model。建议先用 curl 或 SDK 发出一次非流式请求，确认认证和模型正常，再接入更复杂的 Agent、知识库或工作流工具。

## 通用配置

| 配置项 | 填写内容 |
| --- | --- |
| Base URL | **https://www.uucode.org/v1** |
| API Key | 控制台创建的 API Key |
| Model | 模型广场中实际可用的模型 ID |
| API 类型 | OpenAI Compatible，或客户端对应的 Claude / Gemini 格式 |
| Streaming | 首次调试建议关闭，确认成功后再打开 |

常见错误是把 Base URL 填成接口完整路径。例如 OpenAI SDK 的 Base URL 应填写 **https://www.uucode.org/v1**，不要再追加 **/chat/completions**；SDK 会自动追加路径。

## 用环境变量统一配置

推荐在服务端或本地 shell 中设置环境变量：

~~~bash
export OPENAI_API_KEY="YOUR_API_KEY"
export OPENAI_BASE_URL="https://www.uucode.org/v1"
~~~

不同客户端对变量名称的支持不同。如果客户端没有读取 **OPENAI_BASE_URL**，请在它的设置页面手动填写同样的地址。不要把生产 Key 写进前端仓库、配置截图或公开日志。

## OpenAI Python SDK

安装并调用：

~~~bash
pip install openai
~~~

~~~python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url="https://www.uucode.org/v1",
)

response = client.chat.completions.create(
    model="YOUR_MODEL_ID",
    messages=[{"role": "user", "content": "你好，请用一句话介绍自己。"}],
    stream=False,
)

print(response.choices[0].message.content)
~~~

流式调用示例：

~~~python
stream = client.chat.completions.create(
    model="YOUR_MODEL_ID",
    messages=[{"role": "user", "content": "请分三点介绍 API 安全。"}],
    stream=True,
)

for chunk in stream:
    text = chunk.choices[0].delta.content or ""
    print(text, end="", flush=True)
~~~

## OpenAI JavaScript SDK

~~~bash
npm install openai
~~~

~~~javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "https://www.uucode.org/v1",
});

const response = await client.chat.completions.create({
  model: "YOUR_MODEL_ID",
  messages: [{ role: "user", content: "你好" }],
});

console.log(response.choices[0].message.content);
~~~

如果在浏览器端直接调用，API Key 很容易被查看和盗用。生产环境应由自己的后端保存 Key，并由后端调用 UUcode。

## curl 快速验证

### 普通文本请求

~~~bash
curl https://www.uucode.org/v1/chat/completions \\
  -H "Authorization: Bearer $OPENAI_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": false
  }'
~~~

### 流式请求

~~~bash
curl -N https://www.uucode.org/v1/chat/completions \\
  -H "Authorization: Bearer $OPENAI_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "请分三段回答。"}],
    "stream": true
  }'
~~~

### 查看模型

~~~bash
curl https://www.uucode.org/v1/models \\
  -H "Authorization: Bearer $OPENAI_API_KEY"
~~~

如果这个请求失败，先不要继续排查 SDK；请先检查 Key、域名、证书、代理和模型列表。

## 接入 OpenAI 兼容客户端

在支持 OpenAI Compatible 的桌面应用、IDE 插件、工作流工具或 Agent 框架中，按以下顺序填写：

1. 选择 OpenAI Compatible 或 Custom OpenAI Provider。
2. 将 Base URL 填为 **https://www.uucode.org/v1**。
3. 填入 API Key，不要在前后添加空格或换行。
4. 从 **GET /v1/models** 或模型广场复制准确的 Model ID。
5. 先关闭流式和工具调用，确认简单文本请求成功。
6. 再逐项开启流式、图片、函数调用、推理或其他高级参数。

有些客户端会自动把 Base URL 末尾的 **/v1** 追加一次。如果最终请求变成 **/v1/v1/chat/completions**，请按客户端规则去掉一处 **/v1**。

## Claude 客户端

需要使用 Claude Messages 格式的客户端时，选择 Anthropic 或 Claude Provider，并将 API 地址指向站点根地址；完整消息路径是 **/v1/messages**。请求通常需要：

~~~http
Authorization: Bearer YOUR_API_KEY
anthropic-version: 2023-06-01
~~~

如果客户端只支持 **x-api-key**，将同一个 API Key 放入该请求头。不要把 OpenAI 的 **messages** 结构和 Claude 的内容块结构混合使用，具体请求示例见 [API 参考](https://www.uucode.org/docs/api-reference)。

## Gemini 客户端

支持 Gemini 原生协议的客户端应选择 Gemini Provider，并使用：

~~~text
https://www.uucode.org/v1beta
~~~

Gemini 原生请求使用 **contents**、**parts** 和 **generationConfig**。如果客户端只支持 OpenAI Compatible，则改用 **https://www.uucode.org/v1**，并选择网关中已配置的 OpenAI 兼容模型。

## 图片、音频和视频工具

- 图片生成：使用 **POST /v1/images/generations**；参数以模型说明为准。
- 图片编辑：使用 **POST /v1/images/edits**，通常需要上传文件。
- 音频转录：使用 **POST /v1/audio/transcriptions**，确认客户端支持 multipart/form-data。
- 文本转语音：使用 **POST /v1/audio/speech**，响应通常是音频二进制文件。
- 视频生成：使用 **POST /v1/videos** 或站点提供的专用任务接口，创建后需要轮询任务状态。

首次接入多媒体模型时，先使用较小的文件、较短的文本和较低的任务参数验证链路，再逐步提升分辨率、时长或批量数量。

## 代理、超时和重试

- 长文本、图片和视频任务需要比普通文本更长的客户端超时时间。
- 流式请求不要设置过短的读取超时；应区分连接超时与流式空闲超时。
- 429 时读取 **Retry-After**，使用指数退避，不要立即高频重试。
- 5xx 或上游超时时只在请求是幂等或业务允许时重试；视频创建、扣费接口不要盲目重复提交。
- 记录请求时间、模型、状态码和脱敏后的请求标识，排查时不要记录完整 API Key 或用户输入中的敏感信息。

## 客户端排查顺序

1. 访问 **https://www.uucode.org/v1/models**，确认域名、证书和 Key 有效。
2. 复制模型广场中的准确模型 ID。
3. 确认 Base URL 没有重复 **/v1**，也没有少掉协议头。
4. 确认请求头是 Bearer Token，或使用对应原生协议的认证头。
5. 关闭流式、工具调用和多模态内容，发送最简单的文本请求。
6. 检查账户余额、分组权限和模型渠道状态。
7. 最后再开启高级参数，并一次只改一个变量。

仍然失败时，保留状态码、error.message、模型 ID、发生时间和请求 ID，前往 [错误码与排查](https://www.uucode.org/docs/troubleshooting)。不要提交 API Key、完整请求体或包含隐私的用户内容。

---

# 错误码与排查

URL: https://www.uucode.org/docs/troubleshooting

# 错误码与排查

遇到问题时，先记录以下信息：HTTP 状态码、响应中的 error.message 和 error.code、模型 ID、发生时间，以及响应头中的请求 ID。不要提交 API Key、完整请求体或包含隐私的用户内容。

## 标准错误响应

大多数 OpenAI 兼容接口会返回类似结构：

~~~json
{
  "error": {
    "message": "错误描述",
    "type": "invalid_request_error",
    "code": "invalid_request"
  }
}
~~~

具体 message 和 code 会随接口、模型适配器和上游服务变化。排查时优先看 HTTP 状态码和服务端返回的错误信息，不要只根据客户端包装后的异常名称判断。

## 请求 ID

网关会返回用于定位请求的标识。常见响应头包括：

- **X-Oneapi-Request-Id**：网关本地请求 ID。
- **X-Upstream-Request-Id**：上游服务返回的请求 ID（如果上游提供）。

请在客户端日志中保留这些值。向管理员反馈时，提供请求 ID、模型、时间和状态码即可，不要提供 API Key。

## 401 Unauthorized：认证失败

### 常见原因

- 没有发送 Authorization 请求头。
- Bearer 与 API Key 之间缺少空格，或把整段示例文字原样发送。
- Key 前后有空格、换行，复制不完整或已经被删除。
- 把网页登录 Access Token 当成模型 API Key。
- Claude 或 Gemini 客户端使用了错误的协议认证头。

### 排查方式

先用最简单的模型列表请求验证：

~~~bash
curl https://www.uucode.org/v1/models \\
  -H "Authorization: Bearer YOUR_API_KEY"
~~~

确认请求头最终是 **Authorization: Bearer YOUR_API_KEY**。Claude 原生客户端还要检查 **anthropic-version**；Gemini 原生客户端要确认使用的是 **/v1beta** 路径和对应认证方式。认证详情见 [API Key 与认证](https://www.uucode.org/docs/authentication)。

## 400 Bad Request：参数或格式错误

### 常见原因

- model 拼写错误，或请求体不是合法 JSON。
- Chat Completions 使用了缺少 role/content 的 messages。
- Responses、Claude、Gemini 的请求格式混用。
- max_tokens、图像数量、视频时长或其他数量字段超出站点限制。
- 上传接口缺少 file、model，或手动设置了错误的 multipart boundary。
- 当前模型不支持请求中的 tools、图片、音频、流式或其他高级字段。

### 排查方式

1. 从模型广场复制准确的模型 ID。
2. 先删除可选参数，只保留 model 和最简单的文本输入。
3. 确认 Base URL 和协议路径正确。
4. 非流式请求成功后，再逐一添加 temperature、tools、图片或其他参数。
5. 文件上传使用客户端的 multipart 功能，不要手动拼接 boundary。

## 402 Payment Required：余额或额度不足

余额不足可能发生在请求开始前的预扣阶段，也可能与模型倍率、输入长度和输出上限有关。请检查：

- 钱包余额或账户剩余额度。
- 当前模型的计费倍率和分组价格。
- max_tokens、max_output_tokens 等输出上限。
- 图片生成数量、分辨率、质量和批次。
- 视频 seconds、duration、分辨率和其他任务参数。
- 是否有其他并发请求正在消耗额度。

先使用短文本、较小输出上限和低成本模型验证链路。不要通过反复重试余额不足的请求来解决问题。

## 403 Forbidden：没有权限

账户、分组、API Key 或模型渠道可能没有当前接口权限。检查：

- 账户是否被停用或需要完成验证。
- API Key 所属用户和分组是否允许访问该模型。
- 模型是否在模型广场中对当前账户可见。
- 调用的协议是否与模型配置一致。
- 管理员是否限制了并发、来源或接口类型。

如果模型在模型列表中可见但请求仍返回 403，保存请求 ID 后联系管理员，不要不断更换 Key 重试。

## 404 Not Found：路径或任务不存在

常见原因是 Base URL 拼接错误、接口路径写错，或异步任务 ID 不属于当前账户：

- OpenAI SDK 的 Base URL 通常填 **https://www.uucode.org/v1**，不要再追加完整接口路径。
- Gemini 原生路径使用 **/v1beta/models/{model}:generateContent**。
- 视频任务查询必须使用创建响应返回的 task ID。
- 已过期或被清理的视频任务可能无法继续下载。

如果请求变成 **/v1/v1/chat/completions**，说明客户端和手动配置重复追加了版本前缀。

## 413 Request Entity Too Large：请求体过大

常见于大图片、长音频、视频参考文件或压缩请求解压后超过限制。请：

- 压缩或裁剪上传文件，先用小文件验证。
- 减少一次请求中的图片数量和输入文本长度。
- 检查反向代理与网关两层的 body size 配置。
- 不要把大量 base64 内容重复嵌套在 JSON 中。

## 429 Too Many Requests：触发限流

限流可能来自用户、模型、API Key、渠道或系统层。正确处理方式：

1. 读取响应头 **Retry-After**（如果存在）。
2. 使用指数退避，例如逐步等待 1、2、4、8 秒，并设置最大等待时间。
3. 降低并发和请求频率，避免多个 worker 同时立即重试。
4. 对流式或视频任务不要用创建请求的重试逻辑替代状态查询。

429 不一定表示 Key 无效；如果偶发出现，优先检查并发和客户端重试策略。

## 5xx、502、504：上游或网关异常

先区分是偶发上游失败还是请求配置问题：

- 使用同一个 Key 和模型发送一次最简单的非流式文本请求。
- 查询 **GET /v1/models** 确认模型仍可见。
- 检查模型渠道是否暂时不可用、超时或被上游限流。
- 对普通文本请求可在等待后重试；对视频创建、图片生成等可能产生任务或费用的请求，不要盲目重复提交。
- 多次失败时提供本地请求 ID、上游请求 ID、模型和发生时间给管理员。

## 流式请求没有输出或中途断开

### 客户端侧

- curl 使用 **-N**，不要等待整个响应体下载完成。
- 确认请求体中的 **stream** 为 true。
- 使用支持 SSE 的 SDK 或客户端，不要按单个 JSON 解析每一行。
- 增加读取超时，区分连接超时和流式空闲超时。

### 代理侧

反向代理可能缓冲 SSE 或在空闲时关闭连接。检查代理的响应缓冲、读取超时和连接超时配置。先用 curl 直接访问网关排除代理影响，再回到客户端测试。

如果非流式成功、流式失败，通常优先排查 SSE 解析、代理缓冲和超时，而不是更换模型。

## 图片、音频和视频专项排查

### 图片

确认当前模型支持生成或编辑、请求格式符合该模型要求，并控制 **n**、尺寸、质量和输入图片大小。图片响应可能包含 URL 或 base64 数据，客户端应根据返回字段处理，不要假设所有模型都返回同一种格式。

### 音频

转录和翻译接口需要 multipart/form-data，检查 file 字段名、文件格式、文件大小和 model。语音合成接口返回音频二进制，应使用文件输出或二进制读取，不要当作 JSON 文本解析。

### 视频

视频生成是异步任务：

1. 保存创建响应中的任务 ID。
2. 使用对应 GET 路径轮询状态。
3. 只在状态完成后下载 content。
4. 失败时记录任务 ID 和请求 ID，不要立刻重复创建。

轮询应使用逐步增加的间隔，避免因高频查询触发限流。

## 计费和请求参数建议

网关会根据模型、输入输出 token、媒体数量和任务时长计算额度。为避免不必要的扣费或限流：

- 文本请求先设置合理的 max_tokens 或 max_output_tokens。
- 图片、视频和音频先用最小可验证参数测试。
- 对失败的非幂等任务不要自动无限重试。
- 不要把用户输入中的数量字段直接转换为极大批次或时长。
- 遇到余额变化异常，记录请求 ID、模型、时间和响应状态，联系管理员核对用量日志。

## 一键排查清单

~~~text
1. GET https://www.uucode.org/v1/models 是否成功？
2. Authorization 是否为 Bearer + 正确 API Key？
3. Base URL 是否多了或少了 /v1？
4. model 是否从当前模型列表复制？
5. 是否先用最简单的非流式文本请求验证？
6. 是否存在 402 余额不足、403 权限或 429 限流？
7. 是否读取了 error.message、error.code 和请求 ID？
8. 文件、图片、视频请求是否超过大小、时长或数量限制？
9. 流式请求是否使用 SSE 客户端并关闭了代理缓冲？
10. 异步任务是否使用创建响应返回的 ID 查询？
~~~

仍然无法解决时，前往 [API 参考](https://www.uucode.org/docs/api-reference) 对照接口格式，或在提交工单时提供脱敏后的错误信息。请始终保留 API Key、密码、用户隐私和完整业务数据。

---

# API Key 与认证

URL: https://www.uucode.org/docs/authentication

# API Key 与认证

所有公开模型接口都使用站点统一的 API Key 认证。无论你调用 OpenAI 兼容、Claude、Gemini、图像、音频还是视频接口，优先使用同一种方式：在请求头中发送 API Key。

## Base URL

统一接口地址为：

~~~text
https://www.uucode.org/v1
~~~

例如，聊天接口的完整地址是：

~~~text
https://www.uucode.org/v1/chat/completions
~~~

站点会在公开文档中自动替换 **https://www.uucode.org** 占位符。不要把 **/v1** 重复拼接两次，也不要把控制台页面地址当作 API 地址。

## 标准 Bearer Token

推荐所有客户端使用以下请求头：

~~~http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
~~~

curl 示例：

~~~bash
curl https://www.uucode.org/v1/models \\
  -H "Authorization: Bearer YOUR_API_KEY"
~~~

API Key 与网页登录后的 Access Token 不是同一种凭证。调用模型接口时，请在控制台的 **API Key / 令牌** 页面创建并使用 API Key。

## Claude 和 Gemini 原生格式

为了兼容原生客户端，网关也会识别对应协议的认证头：

### Claude Messages

调用 **POST /v1/messages** 时，可以使用标准 Bearer Token；使用 Anthropic 兼容客户端时，通常还需要发送版本头：

~~~http
Authorization: Bearer YOUR_API_KEY
anthropic-version: 2023-06-01
Content-Type: application/json
~~~

如果客户端只能发送 **x-api-key**，可以将 API Key 放在该请求头中。请不要同时配置多个不同的 Key，以免排查时混淆。

### Google Gemini

调用 Gemini 格式接口时可以继续使用 Bearer Token；支持 Gemini 原生配置的客户端也可以将 Key 放在 **x-goog-api-key** 请求头中。Gemini 的模型路径和请求体格式与 OpenAI 兼容接口不同，详见 [API 参考](https://www.uucode.org/docs/api-reference)。

## 创建、使用和撤销 Key

1. 登录控制台，打开 **API Key / 令牌** 页面。
2. 创建 Key，并在生成时立即复制完整值。
3. 为不同应用、环境或团队成员使用独立 Key。
4. 只在服务端环境变量或密钥管理系统中保存 Key。
5. 发现泄露、误提交或不再使用时，立即删除或禁用对应 Key。

建议使用环境变量，而不是把密钥写在源代码中：

~~~bash
export OPENAI_API_KEY="YOUR_API_KEY"
~~~

Python SDK 示例：

~~~python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url="https://www.uucode.org/v1",
)
~~~

## 不要泄露 API Key

- 不要把 Key 写入前端 JavaScript、移动端包或浏览器 localStorage。
- 不要提交到 GitHub、日志、截图、工单或公开聊天。
- 不要把 Key 放在 URL 查询参数中，避免被代理、历史记录和监控系统记录。
- 日志中只保留脱敏后的前缀或指纹，不要打印完整 Key。
- 生产环境与测试环境使用不同 Key，并按最小权限和最短生命周期管理。

如果怀疑 Key 已经泄露，先撤销旧 Key，再创建新 Key；不要只修改客户端配置而保留旧 Key。

## 常见认证错误

| 状态码 | 常见原因 | 排查方式 |
| --- | --- | --- |
| **401 Unauthorized** | Key 缺失、复制不完整、已删除或请求头格式错误 | 检查是否为 **Authorization: Bearer YOUR_API_KEY**，并确认 Key 仍处于启用状态 |
| **403 Forbidden** | 账户、分组或模型权限不足 | 检查账户状态、分组权限和模型是否对当前 Key 开放 |
| **402 Payment Required** | 余额或可用额度不足 | 检查钱包、额度、模型倍率以及本次请求的输出上限 |
| **429 Too Many Requests** | 触发用户、模型或系统限流 | 降低并发，读取 **Retry-After**，使用指数退避后重试 |

如果标准 Bearer 请求可以成功，而某个第三方客户端失败，优先检查该客户端的 Base URL、认证头名称和是否自动追加了 **/v1**。

## 相关页面

- 第一次请求：[快速开始：5 分钟发出第一个请求](https://www.uucode.org/docs/quick-start)
- 接口和请求示例：[API 参考](https://www.uucode.org/docs/api-reference)
- 客户端配置：[工具接入](https://www.uucode.org/docs/tools)
- 状态码排查：[错误码与排查](https://www.uucode.org/docs/troubleshooting)。