# OpenAI API 接入文档与 Claude API 中转教程

查看 KaiyunCode 的 OpenAI 兼容 API、Claude API 中转、Gemini 和图片生成接口接入文档，快速完成 Base URL、API Key、模型参数和调用示例配置。

Canonical: https://kaiyuncode.com/docs
Markdown: https://kaiyuncode.com/docs.md

## Agent 接入要点

KaiyunCode 提供 OpenAI 兼容 API、Anthropic Messages 兼容 API、图片生成、视频生成和客户端工具接入能力。AI Agent 只需要读取本页即可获得基础地址、鉴权方式、常用端点、示例请求和排错方向。

OpenAI 兼容 SDK、Codex CLI 和大多数代理工具使用 https://kaiyuncode.com/v1 作为 Base URL。Anthropic SDK 和 Claude Code 使用站点根地址 https://kaiyuncode.com 作为 Base URL。

- OpenAI 兼容 Base URL：https://kaiyuncode.com/v1
- Anthropic / Claude Code Base URL：https://kaiyuncode.com
- 鉴权方式：Authorization: Bearer APIKEY
- API Key：登录 KaiyunCode 后在密钥管理页创建，并替换示例里的 APIKEY 或“在这里替换成你的_API_KEY”。
- 模型名称：以 KaiyunCode 模型价格页和后台实际开放模型名为准。

## 常用端点

文本、Claude、图片、视频接口可以从下列端点开始接入。同步接口会直接返回结果，异步接口会返回 task_id 或 id，然后通过查询端点轮询。

- POST /v1/chat/completions：OpenAI Chat Completions，适合旧项目、多轮对话和 Gemini 图片生成兼容调用。
- POST /v1/responses：OpenAI Responses，适合新式 OpenAI SDK、Codex CLI 和工具调用链路。
- POST /v1/messages：Anthropic Messages，适合 Claude 模型与 Claude Code 兼容链路。
- POST /v1/images/async/generations：异步文生图任务提交。
- POST /v1/images/async/edits：异步图生图任务提交，使用 multipart/form-data 上传图片。
- GET /v1/images/async/{taskId}：查询异步图片任务。
- POST /v1/videos：提交视频生成或视频续写任务。
- GET /v1/videos/{taskId}：查询视频任务状态和结果 URL。

## Chat Completions 示例

旧版 OpenAI 兼容项目通常只需要替换 baseURL 和 API Key。messages 中放入用户输入，model 使用平台模型列表里的实际可用名称。

### curl

```bash
curl https://kaiyuncode.com/v1/chat/completions \
  -H "Authorization: Bearer APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini-plus",
    "messages": [
      { "role": "user", "content": "你好，请帮我解析项目" }
    ]
  }'
```

## Responses 示例

Responses API 适合新项目和 Codex 等新式 OpenAI 客户端。OpenAI SDK 中 apiKey 填 KaiyunCode API Key，baseURL 填 https://kaiyuncode.com/v1。

### Node.js

```javascript
import OpenAI from "openai"

const client = new OpenAI({
  apiKey: "APIKEY",
  baseURL: "https://kaiyuncode.com/v1"
})

const response = await client.responses.create({
  model: "gpt-5.4-mini-plus",
  input: "你好，给我一个简短的产品卖点"
})

console.log(response.output_text)
```

## Anthropic Messages 示例

Claude 模型按 Anthropic Messages 结构传参。Anthropic SDK 的 base_url 通常填站点根地址，不额外追加 /v1。

### Python

```python
from anthropic import Anthropic

client = Anthropic(
    api_key="APIKEY",
    base_url="https://kaiyuncode.com"
)

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "你好，给我一个简短的产品卖点"}
    ],
)

print(message.content[0].text)
```

## Gemini 图片生成示例

Gemini 图片生成或改图走 /v1/chat/completions。文本和参考图放入 messages[0].content，尺寸与比例放在 extra_body.google.image_config。

### 文生图

```bash
curl https://kaiyuncode.com/v1/chat/completions \
  -H "Authorization: Bearer APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "temperature": 0.8,
    "extra_body": {
      "google": {
        "image_config": {
          "image_size": "1K",
          "aspect_ratio": "1:1"
        }
      }
    },
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "生成一张电商香薰蜡烛主图，暖色棚拍光，背景干净，产品居中。"
          }
        ]
      }
    ]
  }'
```

## GPT Image 2 异步图片示例

GPT Image 2 文生图和图生图都是异步任务。提交成功后读取 task_id，再用 /v1/images/async/{taskId} 查询结果。

### 提交文生图任务

```bash
curl https://kaiyuncode.com/v1/images/async/generations \
  -H "Authorization: Bearer APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "生成一张电商运动水杯主图，白底，真实摄影质感，主体居中，柔和阴影。",
    "size": "1024x1024",
    "quality": "high",
    "background": "opaque",
    "output_format": "png",
    "n": 1
  }'
```

### 查询图片任务

```bash
curl https://kaiyuncode.com/v1/images/async/TASK_ID \
  -H "Authorization: Bearer APIKEY"
```

## 视频生成示例

视频任务使用 /v1/videos 提交，返回 id 或 task_id 后轮询 /v1/videos/{taskId}。完成后读取 video_url、media_url、result_url、metadata.url 或 results[0].url。

### 提交任务

```bash
curl https://kaiyuncode.com/v1/videos \
  -H "Authorization: Bearer APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-v3-fast",
    "prompt": "一只橘猫在窗台上慵懒地舔毛，慢镜头，电影质感",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'
```

### 轮询任务

```bash
curl https://kaiyuncode.com/v1/videos/TASK_ID \
  -H "Authorization: Bearer APIKEY"
```

## 常见排错

- 401 或 Unauthorized：检查 API Key 是否复制完整、是否放在 Authorization: Bearer 后面，Claude Code 还要确认 ANTHROPIC_AUTH_TOKEN 已写入。
- 模型不存在或不可用：把 model 改成 KaiyunCode 模型价格页和后台已开放的模型名称。
- Anthropic SDK 调用失败：确认 base_url 是 https://kaiyuncode.com，而不是 https://kaiyuncode.com/v1。
- OpenAI SDK 调用失败：确认 baseURL 是 https://kaiyuncode.com/v1，并升级到支持目标接口的 SDK 版本。
- 异步任务一直未完成：降低轮询频率到 3-5 秒，最终只在 completed/succeeded/success 状态读取结果 URL。
- 临时媒体 URL 过期：生成成功后尽快下载或转存到自己的对象存储。