GPT88 Agent Docs

POST /v1/chat/completions

对话补全主接口。完全兼容 OpenAI 协议，可在流式与非流式之间切换，支持 function calling 与多模态内容。

端点与认证

POSThttps://api.gpt88.cc/v1/chat/completions

所有请求需在 HTTP Header 中携带 Authorization: Bearer <API_KEY>。请在 Agent API Keys 控制台「API Keys」页面创建一把 Key 后填入。

请求体

请求体为 JSON，常用字段如下：

  • modelstring必填
    要调用的模型 ID，例如 claude-opus-4-7。 可用模型清单通过 GET /v1/models 实时获取， 不同账号可见的模型由控制台权限决定。
  • messagesarray<Message>必填
    多轮对话历史，按时间顺序排列。每个元素包含 role（system / user / assistant / tool）和 content。
  • streamboolean
    是否以 SSE 流式返回。设为 true 时，响应是text/event-stream，每行 data: {...}， 最终以 data: [DONE] 结束。
    默认值：false
  • temperaturenumber
    采样温度，范围 0–2，越大越发散。与 top_p 二选一即可。
    默认值：1
  • top_pnumber
    核采样阈值，范围 0–1。
    默认值：1
  • max_tokensinteger
    本次生成的最大 token 数。模型自身的上下文上限由具体模型决定，请通过 GET /v1/models 查看。
  • stopstring | string[]
    遇到任一字符串时停止生成，最多 4 个。
  • presence_penaltynumber
    范围 -2.0 – 2.0，正值促进话题多样性。
    默认值：0
  • frequency_penaltynumber
    范围 -2.0 – 2.0，正值抑制重复词。
    默认值：0
  • response_formatobject
    指定输出结构。常用：{ "type": "json_object" } 让模型返回严格的 JSON。是否支持取决于模型，未支持时会原样按文本返回。
  • toolsarray<Tool>
    Function calling 工具定义数组。每个 tool 至少包含type（目前为 "function"）和 function（含 name / description / parameters JSON Schema）。
  • tool_choicestring | object
    控制工具调用："auto"（默认）/ "none" / 指定具体 tool 对象。
  • userstring
    终端用户标识，建议透传以便在审计与风控中关联到真实业务用户。

Message 对象

  • role"system" | "user" | "assistant" | "tool"必填
    消息角色。
  • contentstring | array<Part>必填
    文本或多模态内容数组。多模态形如 [{ "type": "text", ... }, { "type": "image_url", ... }]， 是否可用取决于模型本身。
  • namestring
    可选的角色名，常用于多用户对话场景区分发言者。
  • tool_call_idstring
    当 role = "tool" 时，标记这条消息是对哪一次 tool 调用的响应。

基础调用示例

下面是一次最简单的非流式调用：

request bodyjson
{
  "model": "claude-opus-4-7",
  "stream": false,
  "temperature": 0.7,
  "max_tokens": 1024,
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "用一句话介绍 gpt88.cc"}
  ]
}
curl https://api.gpt88.cc/v1/chat/completions \
  -H "Authorization: Bearer $GPT88_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-7",
    "messages": [
      {"role": "user", "content": "用一句话介绍 gpt88.cc"}
    ]
  }'

响应示例

非流式响应直接返回完整 JSON：

200 OKjson
{
  "id": "chatcmpl-9f3a2b8c1d4e5f6a",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "claude-opus-4-7",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "gpt88.cc 是一个统一的大模型 API 网关，OpenAI 兼容协议，多模型一站接入。"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 28,
    "total_tokens": 52
  }
}

响应字段

  • idstring必填
    本次补全的唯一 ID，便于排障关联日志。
  • objectstring必填
    固定为 "chat.completion"。
  • createdinteger必填
    响应生成时间，Unix 秒。
  • modelstring必填
    真正承担本次推理的模型 ID（与请求一致或为内部对齐版本）。
  • choicesarray<Choice>必填
    生成结果数组。每个 choice 含 index / message / finish_reason（stop / length / tool_calls / content_filter）。
  • usageobject必填
    本次调用的 token 统计：prompt_tokens / completion_tokens / total_tokens。 计费按账号定价规则在控制台展示。

流式响应

将 stream 置为 true 后，服务端会以text/event-stream 推送增量。每条事件是一行data: {...} JSON，最后以 data: [DONE] 结束。

curl -N https://api.gpt88.cc/v1/chat/completions \
  -H "Authorization: Bearer $GPT88_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-7",
    "stream": true,
    "messages": [{"role": "user", "content": "讲一个关于 API 网关的冷笑话"}]
  }'

响应片段（精简）：

event-streamtext
data: {"id":"chatcmpl-9f3a","object":"chat.completion.chunk","created":1730000000,"model":"claude-opus-4-7","choices":[{"index":0,"delta":{"role":"assistant","content":""}}]}

data: {"id":"chatcmpl-9f3a","object":"chat.completion.chunk","created":1730000000,"model":"claude-opus-4-7","choices":[{"index":0,"delta":{"content":"gpt88.cc"}}]}

data: {"id":"chatcmpl-9f3a","object":"chat.completion.chunk","created":1730000000,"model":"claude-opus-4-7","choices":[{"index":0,"delta":{"content":" 是一个统一的大模型 API 网关。"}}]}

data: {"id":"chatcmpl-9f3a","object":"chat.completion.chunk","created":1730000000,"model":"claude-opus-4-7","choices":[{"index":0,"finish_reason":"stop","delta":{}}]}

data: [DONE]

使用 tools / function calling

模型可以根据用户请求决定调用某个工具，并在响应中返回tool_calls。在收到调用后，由你的应用执行工具并把结果作为role: "tool" 消息回传给模型，再发起下一轮请求。

curl https://api.gpt88.cc/v1/chat/completions \
  -H "Authorization: Bearer $GPT88_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-7",
    "messages": [{"role": "user", "content": "上海今天天气怎么样？"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "查询某地的当前天气",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string"}
          },
          "required": ["city"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

错误处理

所有错误均以统一结构返回。HTTP 状态码遵循 OpenAI 协议惯例， 详细码表请参阅 错误码 页。

429 Too Many Requestsjson
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded for model claude-opus-4-7",
    "param": null
  }
}