> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yelinai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Completions API | Unified LLM Interface | LaoZhang API

> OpenAI-compatible Chat Completions API. Access GPT-4, Claude, Gemini and 200+ models through a single endpoint. Complete documentation with code examples.

## 接口简介

Chat Completions 是YeLIn AI最核心的接口，用于与AI模型进行对话交流。支持200+AI模型，包括OpenAI、Claude、Gemini、DeepSeek等所有主流大模型。

## 接口信息

**接口地址**：`POST https://api.yelinai.com/v1/chat/completions`
**兼容性**：完全兼容OpenAI官方API格式

## 请求参数

### 必需参数

| 参数         | 类型     | 说明                         |
| ---------- | ------ | -------------------------- |
| `model`    | string | 要使用的模型名称，参考[模型列表](/models) |
| `messages` | array  | 对话消息数组，包含角色和内容             |

### 可选参数

| 参数                  | 类型           | 默认值   | 说明                |
| ------------------- | ------------ | ----- | ----------------- |
| `temperature`       | number       | 1.0   | 控制输出随机性 (0.0-2.0) |
| `max_tokens`        | integer      | 无限制   | 最大输出token数        |
| `top_p`             | number       | 1.0   | 核采样参数 (0.0-1.0)   |
| `frequency_penalty` | number       | 0.0   | 频率惩罚 (-2.0-2.0)   |
| `presence_penalty`  | number       | 0.0   | 存在惩罚 (-2.0-2.0)   |
| `stop`              | string/array | null  | 停止生成的标识符          |
| `stream`            | boolean      | false | 是否流式输出            |
| `n`                 | integer      | 1     | 生成的选择数量           |
| `user`              | string       | null  | 用户标识符             |

## 消息格式

### 基础消息格式

```
{
  "role": "user",
  "content": "你好，请介绍一下你自己"
}
```

### 支持的角色类型

* **`system`**：系统消息，用于设置AI的行为和角色
* **`user`**：用户消息，用户的输入内容
* **`assistant`**：助手消息，AI的回复内容
* **`function`**：函数消息（OpenAI模型支持）
* **`tool`**：工具消息（部分模型支持）

### 多模态消息格式

对于支持图片理解的模型（如GPT-4o、Gemini Pro Vision），可以发送包含图片的消息：

```
{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "这张图片里有什么？"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/image.jpg"
      }
    }
  ]
}
```

## 请求示例

cURL

Node.js

Python

Go

```
curl https://api.yelinai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "system",
        "content": "你是一个专业的AI助手，请用中文回答问题。"
      },
      {
        "role": "user",
        "content": "请介绍一下YeLIn AI平台的特色功能"
      }
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'
```

## 响应格式

### 标准响应

```
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1702855400,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "YeLIn AI是一个企业级专业稳定的AI大模型API中转站..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  }
}
```

### 响应字段说明

| 字段        | 类型      | 说明                        |
| --------- | ------- | ------------------------- |
| `id`      | string  | 请求的唯一标识符                  |
| `object`  | string  | 对象类型，固定为`chat.completion` |
| `created` | integer | 创建时间戳                     |
| `model`   | string  | 使用的模型名称                   |
| `choices` | array   | 生成的选择数组                   |
| `usage`   | object  | token使用情况统计               |

### finish\_reason 取值

* **`stop`**：自然结束
* **`length`**：达到max\_tokens限制
* **`content_filter`**：触发内容过滤
* **`function_call`**：调用函数（OpenAI模型）
* **`tool_calls`**：调用工具（部分模型）

## 流式响应

设置 `"stream": true` 可以启用流式响应，实时获取生成内容：

cURL

Node.js

Python

```
curl https://api.yelinai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "写一首关于AI的诗"}
    ],
    "stream": true
  }'
```

### 流式响应格式

```
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1702855400,"model":"gpt-4o-mini","choices":[{"index":0,"delta":{"role":"assistant","content":"在"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1702855400,"model":"gpt-4o-mini","choices":[{"index":0,"delta":{"content":"数字"},"finish_reason":null}]}

data: [DONE]
```

## 不同模型的特殊用法

### GPT-4o Vision (图像理解)

```
{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "描述这张图片的内容"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/image.jpg",
            "detail": "high"
          }
        }
      ]
    }
  ]
}
```

### Claude 原生格式

Claude模型同时支持OpenAI格式和原生格式。使用原生格式时，需要调用 `/v1/messages` 端点：

```
curl https://api.yelinai.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1000,
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'
```

### O1 系列推理模型

O1系列模型专为复杂推理任务设计，不支持部分参数：

```
{
  "model": "o1-preview",
  "messages": [
    {
      "role": "user",
      "content": "解决这个数学问题：如果一个数的平方等于64，这个数是多少？"
    }
  ]
}
```

O1系列模型不支持 `temperature`、`top_p`、`frequency_penalty` 等参数，也不支持 `system` 角色消息。

## 使用技巧

### 1. 选择合适的模型

日常对话

* **推荐**：GPT-4o Mini、Claude 3.5 Haiku
* **特点**：响应快、成本低、质量好

代码生成

* **推荐**：GPT-4o、Claude 3.5 Sonnet、DeepSeek Coder
* **特点**：代码理解能力强、生成质量高

复杂推理

* **推荐**：O1 Preview、Claude 3 Opus
* **特点**：逻辑推理能力强、适合数学问题

中文处理

* **推荐**：通义千问、GLM-4、文心一言
* **特点**：中文理解和生成能力优秀

### 2. 优化提示词

```
{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "system",
      "content": "你是一个专业的技术文档写作助手。请用清晰、准确的语言回答问题，如果涉及代码，请提供完整的示例。"
    },
    {
      "role": "user",
      "content": "请解释什么是RESTful API，并给出一个Python示例"
    }
  ],
  "temperature": 0.3
}
```

### 3. 控制输出长度

```
{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "用100字以内总结人工智能的发展历程"
    }
  ],
  "max_tokens": 150
}
```

### 4. 使用停止词

```
{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "列出前5个最大的城市："
    }
  ],
  "stop": ["6."]
}
```

## 计费说明

YeLIn AI采用按Token计费模式，不同模型价格不同：

| 模型类型              | 输入价格             | 输出价格            | 特点    |
| ----------------- | ---------------- | --------------- | ----- |
| GPT-4o Mini       | \$0.15/1M tokens | \$0.6/1M tokens | 性价比之王 |
| GPT-4o            | \$5/1M tokens    | \$15/1M tokens  | 多模态能力 |
| Claude 3.5 Sonnet | \$3/1M tokens    | \$15/1M tokens  | 推理能力强 |
| 通义千问 Turbo        | \$0.3/1M tokens  | \$0.6/1M tokens | 中文优化  |

实际费用以控制台显示为准。使用前请确保账户余额充足。

## 错误处理

### 常见错误码

| 错误码 | 说明        | 解决方案           |
| --- | --------- | -------------- |
| 400 | 请求参数错误    | 检查参数格式和必需字段    |
| 401 | API Key无效 | 检查API Key是否正确  |
| 403 | 权限不足      | 确认API Key有足够权限 |
| 429 | 请求过于频繁    | 降低请求频率         |
| 500 | 服务器错误     | 稍后重试或联系支持      |

### 错误响应示例

```
{
  "error": {
    "message": "The model 'gpt-4o-invalid' does not exist",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}
```

## 最佳实践

1. **使用合适的温度值**：创意任务使用0.7-1.0，精确任务使用0.1-0.3
2. **设置合理的max\_tokens**：避免无限制输出导致费用过高
3. **善用system消息**：设置清晰的角色和任务说明
4. **启用流式响应**：提升用户体验，实时显示生成内容
5. **错误重试机制**：实现指数退避重试策略
6. **监控使用情况**：定期检查控制台的使用统计

***

## 查看更多API文档

返回API参考文档主页，查看其他接口使用方法