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

# 文本生成 API

> 通过 AIOAGI 的 OpenAI 兼容接口完成单轮对话、多轮对话、内容生成、代码生成和流式输出。

文本生成 API 基于 OpenAI 兼容的 `POST /chat/completions` 接口。你可以用同一个 AIOAGI API Key 调用控制台可用的 GPT、Claude、DeepSeek、Gemini、Qwen、Vibe Coding 等模型系列。

<Info>
  模型名称、可用范围、上下文长度、价格和支持策略可能变化。请以控制台和开发者指南显示的信息为准。
</Info>

## 功能概述

文本生成接口适合以下场景：

* 智能对话：构建客服助手、问答机器人和个人助理
* 内容创作：生成文章、摘要、标题、邮件和营销文案
* 代码辅助：生成代码、解释报错、重构片段和编写测试
* 知识问答：从输入内容中提取信息、归纳要点和生成结构化答案
* 角色设定：通过 `system` 消息固定回复风格、身份和输出规则

常用基础地址：

```text theme={null}
https://api.aiearth.dev/v1
https://api.aiearth.vip/v1
```

请求路径：

```text theme={null}
POST /chat/completions
```

## 快速开始

<Steps>
  <Step title="准备 API Key">
    在 AIOAGI 控制台创建 API Key，并确认 Token 组额度和模型权限可用。
  </Step>

  <Step title="配置基础地址">
    服务端调用时设置 `base_url`。大多数文本生成场景使用 `https://api.aiearth.dev/v1`。
  </Step>

  <Step title="选择模型">
    在控制台或开发者指南中查看可用模型 ID。示例中的 `gpt-4o-mini` 仅用于演示。
  </Step>

  <Step title="发送消息">
    使用 `messages` 数组传入 `system`、`user` 和 `assistant` 消息。
  </Step>
</Steps>

## 基础对话示例

使用 OpenAI Python SDK 发起单轮文本生成请求：

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AIO_API_KEY"],
    base_url=os.environ.get("AIO_BASE_URL", "https://api.aiearth.dev/v1"),
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "用三句话介绍人工智能的发展历程。"}
    ],
)

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

等价的 `curl` 请求：

```bash theme={null}
curl "https://api.aiearth.dev/v1/chat/completions" \
  -H "Authorization: Bearer $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "用三句话介绍人工智能的发展历程。"
      }
    ]
  }'
```

## 多轮对话示例

多轮对话由应用层维护历史消息。每次请求时，把需要保留的上下文一起传入 `messages`。

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.aiearth.dev/v1",
)

messages = [
    {"role": "system", "content": "你是一个专业的 Python 编程助手。"},
    {"role": "user", "content": "如何读取 CSV 文件？"},
    {"role": "assistant", "content": "可以使用 pandas 的 read_csv() 函数读取 CSV 文件。"},
    {"role": "user", "content": "如何只读取其中两列？"},
]

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
)

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

## 核心参数

<ParamField path="model" type="string" required>
  模型 ID。请填写控制台当前可用的模型名称，例如 GPT、Claude、DeepSeek、Gemini、Qwen 或 Vibe Coding 系列模型。
</ParamField>

<ParamField path="messages" type="array" required>
  对话消息数组。每条消息通常包含 `role` 和 `content`。
</ParamField>

<ParamField path="temperature" type="number">
  控制输出随机性。常见范围为 `0` 到 `2`。数值越低，输出越稳定；数值越高，输出越发散。
</ParamField>

<ParamField path="max_tokens" type="integer">
  限制最大输出长度。该参数可用于控制成本和响应长度。
</ParamField>

<ParamField path="stream" type="boolean">
  是否启用流式输出。设置为 `true` 后，服务端会分块返回模型生成内容。
</ParamField>

### `messages` 角色

<ParamField path="system" type="role">
  定义模型的身份、目标、边界和输出格式。适合放置稳定规则。
</ParamField>

<ParamField path="user" type="role">
  用户输入。每次用户提问通常追加一条 `user` 消息。
</ParamField>

<ParamField path="assistant" type="role">
  历史模型回复。多轮对话中可保留关键回复，帮助模型延续上下文。
</ParamField>

示例：

```json theme={null}
[
  {
    "role": "system",
    "content": "你是一个友好的客服助手。回答要简洁，并先确认用户诉求。"
  },
  {
    "role": "user",
    "content": "我想咨询退款问题。"
  },
  {
    "role": "assistant",
    "content": "可以的。请说明订单状态和退款原因。"
  },
  {
    "role": "user",
    "content": "商品有质量问题。"
  }
]
```

## 流式输出

当你要提升前端体验或处理长文本生成时，可以启用 `stream`。

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AIO_API_KEY"],
    base_url="https://api.aiearth.dev/v1",
)

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "写一段 300 字左右的产品介绍。"}
    ],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="")
```

## 高级用法

### 系统提示

通过 `system` 消息约束模型的行为和输出格式：

```python theme={null}
messages = [
    {
        "role": "system",
        "content": """你是一个企业知识库问答助手。
规则：
1. 只根据用户提供的上下文回答。
2. 不确定时明确说明信息不足。
3. 使用项目符号输出关键结论。
4. 不编造链接、价格或政策。"""
    },
    {
        "role": "user",
        "content": "根据下面资料总结售后流程：..."
    },
]
```

### 角色设定

为不同任务设置稳定角色，可以提高输出一致性。

```python theme={null}
messages = [
    {
        "role": "system",
        "content": "你是一名资深 Python 开发者。优先给出可运行代码，并指出复杂度和边界条件。"
    },
    {
        "role": "user",
        "content": "帮我写一个 CSV 文件去重脚本。"
    },
]
```

### 上下文管理

长对话需要控制历史长度。你可以保留 `system` 消息和最近几轮对话。

```python theme={null}
def trim_messages(messages, max_history=10):
    system_messages = [m for m in messages if m["role"] == "system"]
    non_system = [m for m in messages if m["role"] != "system"]
    return system_messages + non_system[-max_history:]

messages = trim_messages(messages)
```

## 模型选择建议

<Table>
  <thead>
    <tr>
      <th>场景</th>
      <th>选择建议</th>
      <th>说明</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>日常问答</td>
      <td>选择响应快、成本低的通用模型</td>
      <td>适合客服、助手和普通文本处理。</td>
    </tr>

    <tr>
      <td>复杂推理</td>
      <td>选择推理能力更强的模型</td>
      <td>适合规划、数学、严谨分析和复杂决策。</td>
    </tr>

    <tr>
      <td>代码生成</td>
      <td>选择代码能力强的模型或 Vibe Coding 系列</td>
      <td>适合生成补丁、解释仓库和编写测试。</td>
    </tr>

    <tr>
      <td>长文本处理</td>
      <td>选择上下文窗口更长的模型</td>
      <td>适合文档总结、报告分析和多文件输入。</td>
    </tr>

    <tr>
      <td>多语言任务</td>
      <td>选择中英文表现稳定的通用模型</td>
      <td>适合翻译、润色和跨语言问答。</td>
    </tr>
  </tbody>
</Table>

<Warning>
  不同模型的能力、价格和可用状态会变化。正式接入前，请在控制台确认模型 ID、价格、上下文长度和 Token 组权限。
</Warning>

## 最佳实践

### 优化提示词

把任务、背景、输出格式和限制写清楚。

```text theme={null}
请写一篇关于人工智能在医疗领域应用的科普文章。

要求：
- 长度：800 到 1000 字
- 受众：普通读者
- 结构：引言、应用场景、案例分析、未来展望
- 语气：专业但易懂
- 避免编造未给出来源的真实案例
```

### 增加错误处理

生产环境应处理认证、额度、限流、模型不可用和网络异常。

```python theme={null}
import time
from openai import OpenAI, OpenAIError

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.aiearth.dev/v1",
)

def chat_with_retry(messages, model="gpt-4o-mini", max_retries=3):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model=model,
                messages=messages,
            )
            return response.choices[0].message.content
        except OpenAIError:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)
```

### 控制成本

* 为不同场景选择不同模型，不要所有任务都使用最高规格模型
* 使用 `max_tokens` 控制单次输出长度
* 清理不必要的历史消息，避免重复传入长上下文
* 为不同应用创建独立 Token 组，便于统计和限额
* 定期查看控制台用量和余额

## 常见问题

<AccordionGroup>
  <Accordion title="如何计算 token 数量？" icon="calculator">
    你可以使用模型对应的 tokenizer 或估算库进行预估。不同模型的分词方式可能不同，最终计费请以控制台账单和开发者指南说明为准。
  </Accordion>

  <Accordion title="为什么输出被截断？" icon="scissors">
    常见原因包括 `max_tokens` 设置过小、模型上下文窗口不足、输入过长或触发安全策略。可以检查响应中的 `finish_reason`。
  </Accordion>

  <Accordion title="如何实现对话记忆？" icon="messages">
    API 本身不保存你的业务会话。你需要在应用层保存历史消息，并在下一次请求时传入需要保留的 `messages`。
  </Accordion>

  <Accordion title="返回模型不存在怎么办？" icon="circle-question">
    检查 `model` 是否与控制台展示完全一致，并确认当前 API Key 所属 Token 组有该模型权限。
  </Accordion>

  <Accordion title="可以切换加速线路吗？" icon="network-wired">
    可以。通用线路为 `https://api.aiearth.dev/v1`，CDN 加速线路为 `https://api.aiearth.vip/v1`。请按你的网络环境测试后选择。
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={2}>
  <Card title="聊天补全接口参考" icon="messages">
    可在导航中的 **OpenAI 兼容接口** 分组查看 `POST /chat/completions` 的 OpenAPI 参数参考。
  </Card>

  <Card title="模型列表" icon="list">
    可在导航中的 **OpenAI 兼容接口** 分组查看模型列表接口。
  </Card>

  <Card title="文本向量 API" icon="chart-scatter">
    可在导航中的 **OpenAI 兼容接口** 分组查看文本向量接口。
  </Card>

  <Card title="快速开始" icon="rocket" href="/quickstart">
    完成 API Key、端点和第一次模型调用。
  </Card>
</CardGroup>