poeti.ai | 开发者文档
控制台 返回首页

快速入门

通过 poeti.ai 统一接入所有主流 AI 模型，只需几行代码即可开始使用。

Shield

完全兼容 OpenAI API

无需修改现有代码，只需更换 Base URL 和 API Key 即可切换到 poeti.ai

安装依赖

# Python pip install openai # Node.js npm install openai

身份认证

在控制台创建 API Key，用于所有 API 请求的认证。

获取 API Key

  1. 登录到 poeti.ai 控制台
  2. 导航至"API Keys"页面
  3. 点击"创建新 Key"按钮
  4. 为 Key 设置名称和权限
  5. 复制并安全保存生成的 API Key

⚠️ 安全提示：请妥善保管您的 API Key，不要在代码仓库或公开渠道中暴露。建议使用环境变量存储。

第一个请求

Python

from openai import OpenAI # 初始化客户端 client = OpenAI( api_key="your_poeti_api_key", base_url="https://api.poeti.ai/v1" ) # 发送聊天请求 response = client.chat.completions.create( model="gpt-4", messages=[ {"role": "user", "content": "Hello, world!"} ] ) print(response.choices[0].message.content)

Node.js

import OpenAI from 'openai'; // 初始化客户端 const client = new OpenAI({ apiKey: 'your_poeti_api_key', baseURL: 'https://api.poeti.ai/v1' }); // 发送聊天请求 const response = await client.chat.completions.create({ model: 'gpt-4', messages: [ { role: 'user', content: 'Hello, world!' } ] }); console.log(response.choices[0].message.content);

聊天补全 API

与 AI 模型进行对话，生成文本响应。

端点

POST /v1/chat/completions

请求参数

参数 类型 必需 说明
model string 是 模型 ID（如 gpt-4, claude-3-opus）
messages array 是 对话消息列表
temperature number 否 采样温度（0-2，默认 1）
max_tokens integer 否 最大生成 token 数
stream boolean 否 是否流式返回（默认 false）

响应示例

{ "id": "chatcmpl-abc123", "object": "chat.completion", "created": 1677652288, "model": "gpt-4", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! How can I help you today?" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 10, "completion_tokens": 9, "total_tokens": 19 } }

流式响应

实时获取 AI 响应，提升用户体验。

# Python stream = client.chat.completions.create( model="gpt-4", messages=[{"role": "user", "content": "讲个笑话"}], stream=True ) for chunk in stream: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="")

智能路由

poeti.ai 提供 6 种智能路由策略，根据不同场景自动选择最优 API Key。

1. Round Robin（轮询）

依次轮流使用每个 Key，适合负载均衡场景。

strategy: round_robin

2. Weighted Random（加权随机）

根据 weight 按比例分配流量，高权重 Key 获得更多请求。

strategy: weighted

3. Failover（故障转移）

按 priority 优先级顺序使用，失败时自动切换到次优 Key。

strategy: failover

4. Latency-based（延迟优先）

选择平均延迟最低的 Key，适合对响应速度敏感的场景。

strategy: latency

5. Success Rate（成功率优先）

选择成功率最高的 Key，适合对稳定性要求高的场景。

strategy: success_rate

6. Comprehensive（综合评分）- 默认推荐

综合考虑成功率、延迟、权重、健康分数，最均衡的策略。

strategy: comprehensive

💡 推荐：生产环境建议使用 Comprehensive 策略，它会自动平衡成本、速度和稳定性。

Key Pool 管理

每个 Provider 支持配置多个 API Key，实现负载均衡、故障转移和智能调度。

核心功能

多 Key 管理： 每个 Provider 配置多个 API Key，自动选择最优 Key
健康监控： 实时跟踪每个 Key 的成功率、延迟、健康分数
自动故障切换： Key 失败时自动切换到备用 Key，保证服务可用性
CSV 批量导入： 一次性导入多个 Key，提高配置效率

配置示例

在控制台的 提供商管理 页面添加 Key：

  1. 选择 Provider（如 OpenAI、Anthropic）
  2. 点击「添加 Key」按钮
  3. 填写 API Key
  4. 设置权重（1-1000，默认 100）
  5. 设置优先级（0-100，默认 0）
  6. 添加备注（可选）

健康监控指标

指标 说明
health_score 健康分数（0.0-1.0），成功 +0.1，失败 -0.2
success_rate 成功率百分比
latency_avg 平均响应延迟（毫秒）
total_requests 总请求次数

⚠️ 自动禁用：当 Key 连续失败 3 次且成功率低于 50% 时，系统会自动禁用该 Key。5 分钟后会尝试自动恢复。

Provider 接入说明

poeti.ai 支持 8 个主流 AI 提供商，统一 API 接口。

O

OpenAI

GPT-4、GPT-3.5 系列模型

model: "gpt-4", "gpt-4-turbo", "gpt-3.5-turbo"
A

Anthropic

Claude 3 Opus、Sonnet、Haiku 系列

model: "claude-3-opus", "claude-3-sonnet", "claude-3-haiku"
G

Google

Gemini Pro、Gemini Ultra 系列

model: "gemini-pro", "gemini-ultra"
B

AWS Bedrock

Claude on Bedrock、Titan 系列

model: "anthropic.claude-v2", "amazon.titan-text" # 需要配置 AWS 凭证 base_url: "https://bedrock-runtime.us-east-1.amazonaws.com"

注意：Bedrock 需要额外配置 AWS Access Key ID 和 Secret Access Key。

C

Cohere

Command、Command Light 系列

model: "command", "command-light"
M

Mistral AI

Mistral Large、Medium、Small 系列

model: "mistral-large", "mistral-medium"

💡 提示：所有 Provider 都使用统一的 OpenAI 兼容接口，只需修改 model 参数即可切换。

提示词缓存

对于重复的系统提示词，启用缓存可大幅降低成本和延迟。缓存命中可节省 50-90% 成本。

如何启用

# 在 messages 中使用相同的 system prompt response = client.chat.completions.create( model="gpt-4", messages=[ { "role": "system", "content": "你是一个专业的 AI 助手..." # 长文本会被自动缓存 }, {"role": "user", "content": "用户问题"} ] )

缓存规则

System prompt 超过 1024 tokens 时自动缓存
缓存有效期 5 分钟
缓存命中响应时间 < 20ms
节省 50-90% prompt tokens 成本

供应商管理

v2.6.0 新增

供应商（Supplier）是 API Key 的来源机构。v2.6.0 引入供应商管理，支持官方渠道、转售商、自托管和云平台（Bedrock/Azure）四种类型，实现更精细的成本核算和配额控制。

供应商类型

official

官方渠道

直接使用 OpenAI、Anthropic 等厂商官方 API Key。成本最透明，但价格通常较高。

reseller

转售商

通过第三方转售商获取的 API Key，价格通常低于官方但需评估稳定性。

self_hosted

自托管

自己部署的开源模型（如 Ollama, vLLM），成本固定为算力成本，无 Token 费用。

bedrock azure

云平台

AWS Bedrock 或 Azure OpenAI 服务，使用云账号凭证认证，需单独配置 Access Key。

如何添加供应商

  1. 进入控制台 → 供应商管理
  2. 点击「添加供应商」，选择供应商类型
  3. 填写供应商名称和描述
  4. （可选）设置日/月配额上限
  5. 设置单价（用于成本核算）
  6. 保存后，在 Key Pool 中为 Key 关联此供应商

📖 完整文档：详细的供应商管理配置指南请参见 供应商管理专题页。

请求追踪

v2.6.0 新增

v2.6.0 起，每次 API 调用都会自动生成追踪记录（Trace），保存 Token 用量、成本、延迟、路由决策、所用 Provider 等信息，方便排查问题和分析成本。

Trace 记录包含哪些信息？

字段 说明
trace_id 唯一追踪 ID，也通过 X-Trace-ID 响应头返回
model 实际使用的模型名称
provider 实际路由到的提供商（openai/anthropic/bedrock 等）
prompt_tokens / completion_tokens 输入/输出 Token 数量
cost_usd 本次请求的美元成本
latency_ms 端到端响应延迟（毫秒）
routing_strategy 本次使用的路由策略
status success / error / timeout

通过 X-Trace-ID 查找请求

# 从响应头获取 Trace ID curl -i https://api.poeti.ai/v1/chat/completions \ -H "Authorization: Bearer $API_KEY" \ -d '{"model":"gpt-4o","messages":[...]}' # 响应头包含： X-Trace-ID: trace-poeti-7f8e9d0a # 用 Trace ID 查询详情 curl "https://api.poeti.ai/api/v1/request-traces/trace-poeti-7f8e9d0a" \ -H "Authorization: Bearer $API_KEY"

📖 完整文档：在控制台的 请求日志 页面可可视化查看所有追踪记录。API 完整参数见 请求日志文档页。

配额管理

v2.6.0 新增

v2.6.0 引入精细的配额控制系统，支持对每个 Key 设置日/月使用上限，超出配额后自动停用，保护预算不超支。

配额类型

📅

日配额

每天 00:00 UTC 自动重置。适合控制日峰值消耗。

📆

月配额

每月 1 日自动重置。适合控制月度总预算。

配置配额

# 为指定 Provider Key 设置日/月配额（美元） curl -X POST https://api.poeti.ai/api/v1/provider-keys/{key_id}/quota \ -H "Authorization: Bearer $ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "daily_quota_usd": 10.0, "monthly_quota_usd": 200.0, "daily_token_quota": 1000000, "monthly_token_quota": 20000000 }'

⚠️ 配额耗尽行为：当某 Key 达到配额上限，路由器会自动将其标记为不可用，并切换到其他 Key。若所有 Key 都耗尽，API 返回 503 no_available_keys 错误。

最佳实践

1. 合理设置超时时间

建议设置 30-60 秒的超时时间，避免长时间等待。

2. 实现重试机制

网络请求可能失败，建议实现指数退避的重试策略。

3. 监控使用量

定期检查 API 使用统计，及时发现异常调用。

4. 使用提示词缓存

对于重复的系统提示词，启用缓存可大幅降低成本。

常见问题

如何从 OpenAI 迁移到 poeti.ai？

只需更改两个配置：将 base_url 改为 https://api.poeti.ai/v1，将 api_key 改为您的 poeti.ai API Key。其他代码无需修改。

支持哪些 AI 模型？

我们支持 OpenAI（GPT-4, GPT-3.5）、Anthropic（Claude 3）、Google（Gemini）、Mistral AI 和 Cohere 的所有主流模型。查看完整模型列表。

如何处理 API 错误？

我们返回标准的 HTTP 状态码和详细错误信息。建议实现 try-catch 错误处理，并根据错误类型决定是否重试。

有使用限制吗？

免费版有每月 10,000 tokens 的限制。付费版根据套餐不同有不同的配额，详见定价页面。

支持哪些编程语言？

我们提供 RESTful API，支持所有能发送 HTTP 请求的编程语言。官方 SDK 支持 Python 和 Node.js，社区还有 Go、Java、Ruby 等语言的实现。

需要帮助？

我们的技术团队随时为您提供支持

联系支持 打开控制台