文本系列模型

PilotAIHub 文本系列模型 API 兼容 OpenAI Chat Completions 协议，支持流式/非流式调用、多模态输入与多协议入站。

接口地址

Base URL：https://api.pilotaihub.com

对话端点：POST https://api.pilotaihub.com/chat/completions

使用 OpenAI SDK 调用时，base_url 填 https://api.pilotaihub.com（省略末尾的 /chat/completions），SDK 会自动拼接。

1. 对话生成

对话生成接口兼容 OpenAI Chat Completions API，你可以使用任何兼容 OpenAI 协议的 SDK 或 HTTP 客户端调用。网关会根据模型自动路由到对应服务商，并完成认证、计费与日志记录。

1.1 Header 参数

参数名	类型	必需	说明
Authorization	string	是	认证头，格式为 Bearer {API_KEY}，其中 API_KEY 为 PilotAIHub 虚拟 Key（sk-p 开头）。
Content-Type	string	是	固定为 application/json。

Header 示例

Authorization: Bearer sk-p-xxxxxxxxxxxxxxxx
Content-Type: application/json

1.2 Body 参数

以下为常用参数。你也可以传入其他 OpenAI 兼容参数，网关会透传给上游服务商。

参数名	类型	必需	说明
model	string	是	模型代码，可通过 GET /v1/models 接口查询可用模型列表，如 GLM-5.2。
messages	array	是	消息数组，按时间顺序排列对话历史。
messages[].role	string	是	消息角色，可选值：system（系统提示）、user（用户）、assistant（助手）。
messages[].content	string / array	是	消息内容。纯文本场景传字符串；多模态场景传数组，包含 type 为 text / image_url 的内容块。
max_tokens	integer	否	最大生成 token 数。超出则截断，finish_reason 返回 length。
temperature	float	否	采样温度，范围 0.0 - 2.0，默认 1.0。值越大输出越随机。
top_p	float	否	核采样概率，范围 0.0 - 1.0。与 temperature 二选一使用。
stream	boolean	否	是否流式返回（SSE），默认 false。
stream_options	object	否	流式选项，如 {"include_usage": true} 在最后一个 chunk 返回 token 用量。
response_format	object	否	输出格式控制，如 {"type": "json_object"} 强制返回 JSON。
stop	string / array	否	停止词，模型生成到这些字符串时停止。最多 4 个。

1.3 返回格式

网关对不同服务商的返回结构进行了规范化，统一为 OpenAI Chat Completions 格式。

非流式响应

非流式响应示例

{
  "id": "chatcmpl-xxxxxxxx",
  "object": "chat.completion",
  "model": "GLM-5.2",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！有什么可以帮助你的吗？"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 15,
    "total_tokens": 20
  }
}

流式响应（SSE）

流式响应以 text/event-stream 格式返回，每个 chunk 为一行 data: {...}，最后以 data: [DONE] 结束。

流式响应示例

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"你"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"好"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":5,"completion_tokens":15,"total_tokens":20}}

data: [DONE]

1.4 请求示例

非流式请求

curl

curl https://api.pilotaihub.com/chat/completions \
  -H "Authorization: Bearer sk-p-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "GLM-5.2",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.pilotaihub.com",
    api_key="sk-p-xxxxxxxxxxxxxxxx",
)

resp = client.chat.completions.create(
    model="GLM-5.2",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

node

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.pilotaihub.com",
  apiKey: "sk-p-xxxxxxxxxxxxxxxx",
});

const resp = await client.chat.completions.create({
  model: "GLM-5.2",
  messages: [{ role: "user", content: "你好" }],
});
console.log(resp.choices[0].message.content);

流式请求

流式场景

流式请求适合实时输出场景（如聊天对话），首个 token 延迟更低，用户体验更流畅。

curl

curl -N https://api.pilotaihub.com/chat/completions \
  -H "Authorization: Bearer sk-p-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "GLM-5.2",
    "stream": true,
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.pilotaihub.com",
    api_key="sk-p-xxxxxxxxxxxxxxxx",
)

stream = client.chat.completions.create(
    model="GLM-5.2",
    stream=True,
    messages=[{"role": "user", "content": "你好"}],
)

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

多模态请求（视觉理解）

支持视觉理解的模型可以接收图片输入。将 content 字段改为数组，包含 image_url 和 text 内容块。

python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.pilotaihub.com",
    api_key="sk-p-xxxxxxxxxxxxxxxx",
)

resp = client.chat.completions.create(
    model="GLM-5.2",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.jpg"
                    },
                },
                {
                    "type": "text",
                    "text": "请描述这张图片的内容"
                },
            ],
        }
    ],
)
print(resp.choices[0].message.content)

JSON 格式输出

通过 response_format 参数强制模型返回 JSON 格式，适合结构化数据提取场景。

python

from openai import OpenAI
import json

client = OpenAI(
    base_url="https://api.pilotaihub.com",
    api_key="sk-p-xxxxxxxxxxxxxxxx",
)

resp = client.chat.completions.create(
    model="GLM-5.2",
    messages=[
        {"role": "system", "content": "你是一个信息提取助手，只返回 JSON。"},
        {"role": "user", "content": "提取以下文本的姓名和年龄：张三今年28岁。"}
    ],
    response_format={"type": "json_object"},
)

data = json.loads(resp.choices[0].message.content)
print(data)  # {"name": "张三", "age": 28}

2. 多协议入站支持

除了标准的 OpenAI Chat Completions 协议，PilotAIHub 网关还支持以下协议直接入站，无需额外转换即可用对应 SDK 调用：

协议	请求端点	适用 SDK
OpenAI Chat	POST /v1/chat/completions	openai-python / openai-node
Claude Messages	POST /v1/messages	anthropic-sdk-python / anthropic-sdk-node
Gemini	POST /v1beta/models/{model}:generateContent	google-genai

统一认证

无论使用哪种协议入站，均使用 PilotAIHub 虚拟 Key 通过 Authorization: Bearer 头认证，无需为不同协议准备不同的认证方式。

2.1 Claude Messages 协议示例

如果你使用 Anthropic SDK，可将 base_url 指向 PilotAIHub 网关，用虚拟 Key 认证即可调用。

python (anthropic sdk)

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.pilotaihub.com",
    api_key="sk-p-xxxxxxxxxxxxxxxx",
)

message = client.messages.create(
    model="GLM-5.2",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "你好"}
    ],
)
print(message.content[0].text)

3. 错误处理

网关在请求失败时返回 OpenAI 兼容的错误格式，包含错误码与说明信息。

HTTP 状态码	错误码	说明
401	invalid_key	API Key 无效或未提供。
403	model_not_allowed	当前 Key 无权调用该模型。
402	insufficient_balance	账户余额不足。
429	rate_limited	触发限流（RPM / TPM / 并发）。
502	provider_unavailable	上游服务商不可用，网关已尝试所有备选渠道。

错误响应示例

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "RPM limit exceeded",
    "request_id": "req_xxx"
  }
}

重试建议

收到 429 或 502 错误时，建议使用指数退避重试，而非立即重试。网关响应头会返回 Retry-After（秒）建议等待时间。