API 参考文档

poeti.ai 提供完全兼容 OpenAI 格式的统一 AI 接口。无需修改现有代码，只需替换 Base URL 和 API Key 即可接入 100+ AI 模型。

🔗 Base URL： https://api.poeti.ai 协议版本： v1

所有端点一览

方法	端点	说明	认证
POST	/v1/chat/completions	聊天补全（核心接口）	必需
GET	/v1/models	获取支持的模型列表	必需
GET	/api/v1/api-keys	获取 API Key 列表	必需
POST	/api/v1/api-keys	创建新 API Key	必需
GET	/api/v1/usage	获取用量统计	必需
GET	/api/v1/request-traces	获取请求追踪列表 v2.6	必需
GET	/api/v1/request-traces/stats	请求统计汇总 v2.6	必需

认证方式

所有 API 请求需在 HTTP Header 中携带 Bearer Token：

// HTTP Header
Authorization: Bearer sk-poeti-xxxxxxxxxxxx
                

聊天补全

核心接口，兼容 OpenAI Chat Completions API 格式。

POST /v1/chat/completions

请求参数

参数名	类型	必需	说明
model	string	必需	模型 ID，如 `gpt-4o`、`claude-3-5-sonnet`
messages	array	必需	对话消息列表，每条含 `role`（system/user/assistant）和 `content`
temperature	number	可选	随机性控制（0~2，默认 1.0）。越高越随机，越低越确定
max_tokens	integer	可选	最大生成 token 数。不同模型上限不同
stream	boolean	可选	是否使用 SSE 流式返回（默认 false）
top_p	number	可选	Nucleus sampling 概率阈值（0~1）
presence_penalty	number	可选	抑制重复话题（-2.0~2.0）
frequency_penalty	number	可选	抑制词频重复（-2.0~2.0）
user	string	可选	终端用户 ID，用于监控和审计

请求示例

cURL

Python

Node.js

Go

# 基础请求示例
curl https://api.poeti.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $POETI_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "解释量子纠缠"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024
  }'
                

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-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "解释量子纠缠"}
    ],
    temperature=0.7,
    max_tokens=1024
)

print(response.choices[0].message.content)
# 输出: X-Trace-ID 可在响应头中找到，用于调试
                

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-4o',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: '解释量子纠缠' }
  ],
  temperature: 0.7,
  max_tokens: 1024,
});

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

package main

import (
    "context"
    "fmt"
    openai "github.com/sashabaranov/go-openai"
)

func main() {
    config := openai.DefaultConfig("your_poeti_api_key")
    config.BaseURL = "https://api.poeti.ai/v1"
    client := openai.NewClientWithConfig(config)

    resp, err := client.CreateChatCompletion(
        context.Background(),
        openai.ChatCompletionRequest{
            Model: "gpt-4o",
            Messages: []openai.ChatCompletionMessage{
                {Role: "system", Content: "You are a helpful assistant."},
                {Role: "user", Content: "解释量子纠缠"},
            },
        },
    )
    if err != nil {
        panic(err)
    }
    fmt.Println(resp.Choices[0].Message.Content)
}
                

响应格式

// 非流式响应 (stream: false)
{
  "id": "chatcmpl-poeti-a1b2c3d4",
  "object": "chat.completion",
  "created": 1712678400,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "量子纠缠是一种量子力学现象..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 312,
    "total_tokens": 340
  }
}
                

💡 响应头：每个请求会返回 X-Trace-ID 响应头，可用于在请求日志中查找具体调用记录。

流式响应（Stream）

设置 stream: true 后，服务器通过 Server-Sent Events (SSE) 逐块返回内容：

# Python 流式示例
stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "写一首关于春天的诗"}],
    stream=True
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta is not None:
        print(delta, end="", flush=True)
                

// SSE 流数据格式
data: {"id":"chatcmpl-...","choices":[{"delta":{"content":"量"},"index":0}]}
data: {"id":"chatcmpl-...","choices":[{"delta":{"content":"子"},"index":0}]}
data: {"id":"chatcmpl-...","choices":[{"delta":{},"finish_reason":"stop","index":0}]}
data: [DONE]
                

模型列表

获取当前平台支持的所有 AI 模型。

GET /v1/models

# 获取所有可用模型
curl https://api.poeti.ai/v1/models \
  -H "Authorization: Bearer $POETI_API_KEY"
                

响应格式

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "created": 1712678400,
      "owned_by": "openai"
    },
    {
      "id": "claude-3-5-sonnet-20241022",
      "object": "model",
      "created": 1712678400,
      "owned_by": "anthropic"
    }
  ]
}
                

完整的模型列表（含价格和上下文长度）请参见支持的模型。

API Keys 管理

创建和管理访问 poeti.ai 平台的 API Keys。

GET /api/v1/api-keys

# 获取当前用户的所有 API Key
curl https://api.poeti.ai/api/v1/api-keys \
  -H "Authorization: Bearer $POETI_API_KEY"
                

// 响应示例
{
  "code": 200,
  "data": [
    {
      "id": 1,
      "name": "生产环境 Key",
      "key_prefix": "sk-poeti-a1b2...",
      "is_active": true,
      "total_requests": 15420,
      "total_cost": 12.84,
      "created_at": "2026-01-15T08:00:00Z"
    }
  ]
}
                

POST /api/v1/api-keys

参数名	类型	必需	说明
name	string	必需	API Key 的名称（便于识别）
monthly_budget	number	可选	月度预算上限（美元），0 表示不限制
rate_limit	integer	可选	每分钟请求数限制，0 表示不限制

# 创建新 API Key
curl -X POST https://api.poeti.ai/api/v1/api-keys \
  -H "Authorization: Bearer $POETI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "我的应用",
    "monthly_budget": 50.0,
    "rate_limit": 100
  }'
                

用量统计

查询 Token 用量和成本统计。

GET /api/v1/usage

Query 参数	类型	说明
date_from	string	开始日期，ISO 8601 格式（如 2026-04-01）
date_to	string	结束日期
model	string	按模型过滤

# 查询本月用量
curl "https://api.poeti.ai/api/v1/usage?date_from=2026-04-01&date_to=2026-04-30" \
  -H "Authorization: Bearer $POETI_API_KEY"
                

// 响应示例
{
  "code": 200,
  "data": {
    "total_requests": 8432,
    "total_prompt_tokens": 1240580,
    "total_completion_tokens": 845230,
    "total_tokens": 2085810,
    "total_cost_usd": 24.56,
    "by_model": [
      {
        "model": "gpt-4o",
        "requests": 3210,
        "tokens": 980450,
        "cost_usd": 14.30
      }
    ]
  }
}
                

请求追踪 API

v2.6.0 新增

查询每条请求的详细追踪记录，包含成本分解、延迟、所用 Key 等信息。

✅ v2.6.0 新功能：每次 API 调用都会自动生成 Trace 记录。响应头包含 X-Trace-ID，可用于快速定位单条请求。

GET /api/v1/request-traces

Query 参数	类型	说明
page	integer	页码，从 1 开始（默认 1）
page_size	integer	每页条数（默认 20，最大 100）
model	string	按模型名称过滤
status	string	`success` \| `error` \| `timeout`
date_from	string	开始时间（ISO 8601）
date_to	string	结束时间（ISO 8601）

# 查询最近 20 条失败请求
curl "https://api.poeti.ai/api/v1/request-traces?status=error&page_size=20" \
  -H "Authorization: Bearer $POETI_API_KEY"
                

// 响应示例
{
  "code": 200,
  "data": {
    "items": [
      {
        "trace_id": "trace-poeti-7f8e9d0a",
        "model": "gpt-4o",
        "provider": "openai",
        "status": "success",
        "prompt_tokens": 128,
        "completion_tokens": 256,
        "cost_usd": 0.00512,
        "latency_ms": 843,
        "routing_strategy": "comprehensive",
        "created_at": "2026-04-09T14:23:18Z"
      }
    ],
    "total": 15420,
    "page": 1,
    "page_size": 20
  }
}
                

GET /api/v1/request-traces/stats

// 聚合统计响应
{
  "total_requests": 15420,
  "success_count": 15210,
  "error_count": 210,
  "total_tokens": 8450230,
  "total_cost_usd": 42.18,
  "avg_latency_ms": 723,
  "avg_cost_per_request": 0.00274
}
                

错误码参考

所有错误响应遵循统一格式，包含 HTTP 状态码和业务错误码。

// 错误响应格式
{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked.",
    "status": 401
  }
}
                

HTTP 状态	错误码	说明	处理建议
400	bad_request	请求参数格式错误	检查请求体格式
401	invalid_api_key	API Key 无效或已过期	重新生成 API Key
403	forbidden	无权限访问该资源	检查 Key 权限范围
429	rate_limit_exceeded	请求频率超过限制	指数退避重试
429	quota_exceeded	月度配额已耗尽	升级套餐或等待下月
500	provider_error	上游 AI 提供商返回错误	稍后重试，检查提供商状态
503	no_available_keys	当前无可用 API Key（全部达到配额或禁用）	检查 Key Pool 状态，补充 Key
504	timeout	请求超时（默认 60s）	减小 max_tokens 或重试

重试策略

import time, openai

def chat_with_retry(client, **kwargs):
    max_retries = 3
    wait = 1
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)
        except openai.RateLimitError:
            if attempt == max_retries - 1: raise
            time.sleep(wait)
            wait *= 2  # 指数退避
        except openai.APIStatusError as e:
            if e.status_code >= 500:
                time.sleep(wait)
                wait *= 2
            else:
                raise
                