Skip to main content

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 基于 OpenAI 兼容的 POST /chat/completions 接口。你可以用同一个 AIOAGI API Key 调用控制台可用的 GPT、Claude、DeepSeek、Gemini、Qwen、Vibe Coding 等模型系列。
模型名称、可用范围、上下文长度、价格和支持策略可能变化。请以控制台和开发者指南显示的信息为准。

​
功能概述

文本生成接口适合以下场景：
  • 智能对话：构建客服助手、问答机器人和个人助理
  • 内容创作：生成文章、摘要、标题、邮件和营销文案
  • 代码辅助：生成代码、解释报错、重构片段和编写测试
  • 知识问答：从输入内容中提取信息、归纳要点和生成结构化答案
  • 角色设定：通过 system 消息固定回复风格、身份和输出规则
常用基础地址： 
https://api.aiearth.dev/v1
https://api.aiearth.vip/v1
请求路径： 
POST /chat/completions

​
快速开始

1

准备 API Key

在 AIOAGI 控制台创建 API Key，并确认 Token 组额度和模型权限可用。
2

配置基础地址

服务端调用时设置 base_url。大多数文本生成场景使用 https://api.aiearth.dev/v1。
3

选择模型

在控制台或开发者指南中查看可用模型 ID。示例中的 gpt-4o-mini 仅用于演示。
4

发送消息

使用 messages 数组传入 system、user 和 assistant 消息。

​
基础对话示例

使用 OpenAI Python SDK 发起单轮文本生成请求： 
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 请求： 
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。 
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)

​
核心参数

​
model
string
required
模型 ID。请填写控制台当前可用的模型名称，例如 GPT、Claude、DeepSeek、Gemini、Qwen 或 Vibe Coding 系列模型。
​
messages
array
required
对话消息数组。每条消息通常包含 role 和 content。
​
temperature
number
控制输出随机性。常见范围为 0 到 2。数值越低，输出越稳定；数值越高，输出越发散。
​
max_tokens
integer
限制最大输出长度。该参数可用于控制成本和响应长度。
​
stream
boolean
是否启用流式输出。设置为 true 后，服务端会分块返回模型生成内容。

​
messages 角色

​
system
role
定义模型的身份、目标、边界和输出格式。适合放置稳定规则。
​
user
role
用户输入。每次用户提问通常追加一条 user 消息。
​
assistant
role
历史模型回复。多轮对话中可保留关键回复，帮助模型延续上下文。
示例： 
[
  {
    "role": "system",
    "content": "你是一个友好的客服助手。回答要简洁，并先确认用户诉求。"
  },
  {
    "role": "user",
    "content": "我想咨询退款问题。"
  },
  {
    "role": "assistant",
    "content": "可以的。请说明订单状态和退款原因。"
  },
  {
    "role": "user",
    "content": "商品有质量问题。"
  }
]

​
流式输出

当你要提升前端体验或处理长文本生成时，可以启用 stream。 
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 消息约束模型的行为和输出格式： 
messages = [
    {
        "role": "system",
        "content": """你是一个企业知识库问答助手。
规则：
1. 只根据用户提供的上下文回答。
2. 不确定时明确说明信息不足。
3. 使用项目符号输出关键结论。
4. 不编造链接、价格或政策。"""
    },
    {
        "role": "user",
        "content": "根据下面资料总结售后流程：..."
    },
]

​
角色设定

为不同任务设置稳定角色，可以提高输出一致性。 
messages = [
    {
        "role": "system",
        "content": "你是一名资深 Python 开发者。优先给出可运行代码，并指出复杂度和边界条件。"
    },
    {
        "role": "user",
        "content": "帮我写一个 CSV 文件去重脚本。"
    },
]

​
上下文管理

长对话需要控制历史长度。你可以保留 system 消息和最近几轮对话。 
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)

​
模型选择建议

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

​
最佳实践

​
优化提示词

把任务、背景、输出格式和限制写清楚。 
请写一篇关于人工智能在医疗领域应用的科普文章。

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

​
增加错误处理

生产环境应处理认证、额度、限流、模型不可用和网络异常。 
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 组，便于统计和限额
  • 定期查看控制台用量和余额

​
常见问题

你可以使用模型对应的 tokenizer 或估算库进行预估。不同模型的分词方式可能不同，最终计费请以控制台账单和开发者指南说明为准。
常见原因包括 max_tokens 设置过小、模型上下文窗口不足、输入过长或触发安全策略。可以检查响应中的 finish_reason。
API 本身不保存你的业务会话。你需要在应用层保存历史消息，并在下一次请求时传入需要保留的 messages。
检查 model 是否与控制台展示完全一致，并确认当前 API Key 所属 Token 组有该模型权限。
可以。通用线路为 https://api.aiearth.dev/v1，CDN 加速线路为 https://api.aiearth.vip/v1。请按你的网络环境测试后选择。

​
相关文档

聊天补全接口参考

可在导航中的 OpenAI 兼容接口 分组查看 POST /chat/completions 的 OpenAPI 参数参考。

模型列表

可在导航中的 OpenAI 兼容接口 分组查看模型列表接口。

文本向量 API

可在导航中的 OpenAI 兼容接口 分组查看文本向量接口。

快速开始

完成 API Key、端点和第一次模型调用。