# TyinAPI 模型 API 使用教程

本文档说明如何在 TyinAPI 中创建 API Key，并在常见 SDK 或客户端里调用模型。

## 1. 登录控制台

1. 打开 `https://api.yinntag.top/`。
2. 点击顶部导航栏的「控制台」。
3. 使用管理员或普通用户账号登录。

## 2. 创建 API Key

1. 进入「控制台」。
2. 找到「令牌」或「API Token」相关菜单。
3. 点击「新建令牌」。
4. 设置令牌名称、额度或过期时间。
5. 保存后复制生成的 API Key。

> API Key 只会在创建后完整展示一次，请妥善保存。不要把 Key 提交到 GitHub、前端代码或公开文档中。

## 3. 基础配置

在任何 OpenAI 兼容客户端中使用以下配置：

```text
Base URL: https://api.yinntag.top/v1
API Key: 你在 TyinAPI 控制台创建的令牌
```

模型名称以「模型广场」或管理员后台实际启用的名称为准，例如：

```text
gpt-4o-mini
deepseek-chat
claude-3-5-sonnet-latest
gemini-1.5-pro
```

如果某个模型返回不存在，请先确认模型广场中是否已启用，或者在管理员后台检查渠道和模型映射。

## 4. curl 调用示例

```bash
curl https://api.yinntag.top/v1/chat/completions \
  -H "Authorization: Bearer $TYINAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "你是一个简洁可靠的助手。"},
      {"role": "user", "content": "用三句话介绍 TyinAPI。"}
    ],
    "temperature": 0.7
  }'
```

## 5. Python SDK 示例

```python
from openai import OpenAI

client = OpenAI(
    api_key="你的 TyinAPI Key",
    base_url="https://api.yinntag.top/v1",
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "你是一个简洁可靠的助手。"},
        {"role": "user", "content": "写一个 Python 快速排序示例。"},
    ],
)

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

## 6. Node.js SDK 示例

```js
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TYINAPI_KEY,
  baseURL: "https://api.yinntag.top/v1",
});

const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [
    { role: "system", content: "你是一个简洁可靠的助手。" },
    { role: "user", content: "给我一个产品需求文档大纲。" },
  ],
});

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

## 7. Cherry Studio / Lobe Chat / Open WebUI 配置

通用配置方式如下：

```text
Provider 类型: OpenAI Compatible / OpenAI 兼容
API Host / Base URL: https://api.yinntag.top/v1
API Key: 你的 TyinAPI Key
Model: 选择模型广场中可用的模型名称
```

保存后发送一条测试消息。如果客户端支持模型列表自动拉取，可以刷新模型列表；否则手动填写模型名称。

## 8. 管理员添加上游渠道

如果你是管理员，并且需要接入新的上游模型渠道：

1. 进入「控制台」的管理员区域。
2. 打开「渠道」管理。
3. 新建渠道，选择对应供应商或 OpenAI 兼容类型。
4. 填写上游 Base URL、上游 API Key 和可用模型。
5. 保存后进行测试。
6. 在「模型」或「模型广场」中确认模型已展示给用户。

## 9. 常见问题

### 401 Unauthorized

API Key 错误、过期、被禁用，或请求头没有包含：

```text
Authorization: Bearer 你的 TyinAPI Key
```

### 404 model not found

模型名称不存在、拼写错误，或管理员没有启用该模型。

### 429 Too Many Requests

请求频率过高或额度不足。请降低并发、检查令牌额度，或联系管理员调整限额。

### 请求成功但回复很慢

可能是上游模型响应慢、网络波动或模型正在排队。可以换用更快模型，或降低上下文长度。