# GPT-6 Astra — /chat/completions

GPT-6 Astra 对话接口（OpenAI）：GPT-6 家族的旗舰。105 万 token 上下文、单次最多输出 128,000 token，思考深度 low 到 max 五档可调，支持图片输入、工具调用和 JSON 输出。兼容 OpenAI SDK，也可以用 /v1/responses 调用。

**端点:** `POST https://nezhagate.com/v1/chat/completions`

## 快速开始

两步跑通：先发一个普通请求，再试流式输出。把 YOUR_API_KEY 换成你的 Key，下面的命令可以直接运行。接口和 OpenAI 的 Chat Completions 一致，已有的 OpenAI 代码只要改 `base_url` 和 `model`。

**第 1 步 · 发送请求**

```
curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "messages": [{"role": "user", "content": "用一句话解释什么是光合作用"}]}'
```

返回（HTTP 200）

```
{
  "id": "chatcmpl-7f3c9a1e2b4d6f8a",
  "object": "chat.completion",
  "created": 1791281400,
  "model": "gpt-6-astra",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "光合作用是植物利用阳光，把二氧化碳和水转化成糖并释放氧气的过程。",
        "reasoning_content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 186,
    "total_tokens": 204,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 144}
  }
}
```

`message.content` 是回答，`message.reasoning_content` 是思考过程。`usage` 是这一单计费用的 token 数：思考 token 算在 `completion_tokens` 里，按输出价计费。

**第 2 步 · 流式输出（推荐）**

```
curl -N https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "stream": true, "messages": [{"role": "user", "content": "用一句话解释什么是光合作用"}]}'
```

流式返回标准的 SSE：每一块的正文在 `choices[0].delta.content`，最后一块带 `usage`，以 `data: [DONE]` 结束。回答长、或者模型要先思考时，请用流式：非流式请求最长约 10 分钟，超过会被断开。

**Python（OpenAI SDK）**

```
from openai import OpenAI

client = OpenAI(base_url="https://nezhagate.com/v1", api_key="YOUR_API_KEY")

# 1. 一问一答
resp = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[{"role": "user", "content": "用一句话解释什么是光合作用"}],
)
print(resp.choices[0].message.content)

# 2. 流式输出
stream = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[{"role": "user", "content": "用一句话解释什么是光合作用"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
```

## 认证
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 规格速览

| 上下文窗口 | 1,050,000 token |
| --- | --- |
| 单次最多输出 | 128,000 token |
| 输入 | 文本、图片 |
| 思考 | 按 `reasoning_effort` 思考（不传按 medium），思考摘要在 `reasoning_content` 返回 |
| 工具调用 | 支持（OpenAI `tools` 格式） |
| JSON 输出 | 支持（`response_format`） |
| 联网搜索 | 支持（`web_search: true`，搜索本身不收费） |
| 接口 | /v1/chat/completions · /v1/responses |
| 流式输出 | 支持（`stream: true`，SSE） |
| 计费方式 | 按 token：输入、输出（含思考）和缓存命中分别计价，失败不收费 |

## 请求参数

`POST /v1/chat/completions` 的请求体（JSON），和 OpenAI 的 Chat Completions 相同。下表是常用参数，以及它们在这个模型上的实际效果：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| model | string | 是 | 模型 id：`gpt-6-astra`。 |
| messages | array | 是 | 对话消息数组，每条有 `role`（`system` / `user` / `assistant` / `tool`）和 `content`。`content` 可以是字符串，也可以是 `text` 和 `image_url` 组成的数组（看图，见下文）。多轮对话把历史消息按顺序全部带上。 |
| stream | boolean | 否 | `true` 时以 SSE 流式返回，最后一块带 `usage`。默认 `false`。 |
| max_tokens | integer | 否 | 这个模型不接受输出上限：`max_tokens` / `max_completion_tokens` 会被忽略（不报错）。想要短回答，请在提示词里说明。 |
| temperature / top_p | number | 否 | 这个模型不接受采样参数，传了会被忽略（不报错）。 |
| reasoning_effort | string | 否 | 思考深度：low / medium / high / xhigh / max，默认 medium。档位越高想得越久、越稳，也越慢、输出 token 越多。也可以把档位写进型号名，例如 `gpt-6-astra-high`。 |
| tools / tool_choice | array / string | 否 | 函数调用，OpenAI 标准格式。模型要调用时返回 `finish_reason: "tool_calls"` 和 `tool_calls`，见下文。 |
| response_format | object | 否 | `{"type": "json_object"}` 让模型只输出合法的 JSON；提示词里也要写明要 JSON 以及有哪些字段。 |
| web_search | boolean | 否 | `true` 时先联网搜索，把结果作为参考资料交给模型，见下文。 |

`frequency_penalty`、`presence_penalty` 同样会被忽略。其余 OpenAI 参数原样转给模型。

## 价格

按 token 计费，价格实时读取计费表（每百万 token）。只按成功请求的实际用量收费：失败、超时、被拒都不收费。1 积分 = $0.005。

| 类型 | 美元 / 百万 token | 积分 / 百万 token |
| --- | --- | --- |
| 输入 | $3.00 | 600 |
| 输出（含思考） | $15.00 | 3000 |
| 缓存命中 | $0.30 | 60 |

举例：输入 2,000 token、输出 1,000 token（含思考）的一次请求约 $0.021。

## 思考

`reasoning_effort` 可选 low / medium / high / xhigh / max，不传时网关按 medium 请求。档位越高想得越久、答得越稳，也越慢、输出 token 越多；简单问答用 low 就够。

思考摘要在 `message.reasoning_content` 返回（流式在 `delta.reasoning_content`）。也可以把档位写进型号名：`gpt-6-astra-low`、`gpt-6-astra-high`、`gpt-6-astra-xhigh`，效果相同，按 `gpt-6-astra` 计费。

用 /v1/responses 时，思考深度写在 `reasoning.effort`；要返回思考摘要，需要自己传 `reasoning.summary`（网关不会替你加）。

思考 token 计入 `usage.completion_tokens`，按输出价计费（部分模型另在 `completion_tokens_details.reasoning_tokens` 给出明细）。

## 提示缓存

不需要任何参数：重复的长前缀（同一段系统提示词、多轮对话前面的部分）可能被模型方自动缓存，命中的部分按更低的缓存价计费。是否缓存、命中多少由模型方决定；把固定不变的内容放在消息最前面，命中的机会更大。

命中的 token 数在 `usage.prompt_tokens_details.cached_tokens` 里返回，这部分按缓存命中价计费，其余输入按输入价。

## 看图（图片输入）

在 `content` 数组里放 `image_url`。推荐用 base64 的 data URI（`data:image/png;base64,...`），所有线路都能读到；公网图片链接要由线路去下载，个别线路可能取不到或超时。图片按模型方的规则折算成输入 token。

```
curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "messages": [{"role": "user", "content": [{"type": "text", "text": "这张图里有什么"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}}]}]}'
```

## 工具调用（Function Calling）

在 `tools` 里用 JSON Schema 描述函数。模型决定调用时返回 `finish_reason: "tool_calls"`，`message.tool_calls` 里是函数名和参数（JSON 字符串）。

```
curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "messages": [{"role": "user", "content": "上海现在天气怎么样"}], "tools": [{"type": "function", "function": {"name": "get_weather", "description": "Current weather of a city", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}}}]}'
```

执行函数后，把结果作为一条 `role: "tool"` 的消息（带上对应的 `tool_call_id`）追加到对话里再请求一次，模型会据此给出最终回答。`tool_choice` 可以是 `auto`、`none`、`required`，或指定某个函数。

## Responses 接口（/v1/responses）

这个模型也可以用 OpenAI 的 Responses 接口调用，Codex 等工具用的就是它。请求和返回都按 OpenAI 的 Responses 格式：输入放在 `input`，思考深度写在 `reasoning.effort`。

```
curl https://nezhagate.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "input": "用一句话解释什么是光合作用", "reasoning": {"effort": "medium", "summary": "auto"}}'
```

这个接口不会替你加默认思考档，也不会自动返回思考摘要，需要时像上面这样传 `"summary": "auto"`。计费和对话接口相同；联网搜索只在 /v1/chat/completions 上提供。

## 联网搜索

请求里加 `"web_search": true`（或在 `tools` 里放 `{"type": "web_search"}`）：网关先根据对话实时搜索，把最多 5 条结果和链接作为参考资料交给模型，模型再作答并标注来源。搜索本身不收费，参考资料按输入 token 计费。

```
curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "web_search": true, "messages": [{"role": "user", "content": "今天有哪些重要的科技新闻"}]}'
```

## 线路与稳定性

- 每个模型背后有多条线路。一条线路出错、超时或满载时，网关会在开始返回内容之前自动换到下一条，不需要你重试，也不会重复收费。

- 流式请求一旦开始输出就不再换线：中途断开时，按断开前已经产生的用量计费（见 [计费与退款](https://nezhagate.com/docs/guide/billing)）。

- 所有线路都满载时返回 429 并带 `Retry-After`，按它的秒数等待后重试；失败的请求不计费。各模型的状态见 [服务状态](https://nezhagate.com/status)。

## 错误与退款

出错时返回一个 `error` 对象（`message`、`type`、`code`、`param`），请按 HTTP 状态码和 `code` 判断，不要匹配 `message` 的文字。失败的请求不计费，完整列表见 [错误码](https://nezhagate.com/docs/guide/errors)。

| HTTP | code | 原因 | 怎么办 |
| --- | --- | --- | --- |
| 400 | invalid_messages / invalid_role / invalid_max_tokens | 对话请求的 `messages` 缺失、为空或格式不对，`role` 不在允许的范围，或 `max_tokens` 不是正整数。`param` 指出是哪个字段。 | 修正 `param` 指出的字段。 |
| 400 | model_not_found | 型号写错、没有传 `model`，或这个型号不能用在这个接口上（例如拿对话模型调生图接口）。 | 以 `GET /v1/models` 或 [API 手册](https://nezhagate.com/docs/api) 里的模型 id 为准。 |
| 400 | max_tokens_too_small | 思考型模型把 `max_tokens` 全部用在了思考上，没有写出正文（非流式对话）。 | 调大 `max_tokens` 后重试。 |
| 4xx | invalid_request | 模型方拒绝了请求（例如上下文超长、参数不支持），状态码和 `message` 按模型方的原样返回，`code` 是模型方给出的值。 | 按 `message` 修改请求。 |
| 401 | invalid_api_key | Key 不存在、已删除或已停用，或者账号已停用。 | 到控制台「API Keys」页面检查这把 Key。 |
| 402 | insufficient_quota | 余额不够预扣这一单。网关先按这一单可能的最高费用预扣，同时发很多请求时也可能出现。 | 如果是并发突发，稍等几秒重试；否则充值。 |
| 403 | permission_denied | 这个模型不在这把 Key 的模型白名单里。 | 换成白名单里的模型，或在控制台修改白名单。 |
| 429 | rate_limit_exceeded | 超过了这把 Key 设置的每分钟请求数（按最近 60 秒计）。不带 `Retry-After`。 | 等几秒再试，或在控制台调高这把 Key 的上限。 |
| 429 | rate_limit_exceeded | 这个模型的所有线路都已满载，请求没有发出。只出现在对话类接口：图片和视频任务不会被拒，而是排队。OpenAI 兼容接口带 `Retry-After`。 | 按 `Retry-After` 的秒数等待后重试。 |
| 502 | upstream_timeout | 线路超时，包括迟迟没有返回第一个字。 | 重试；长回答建议用 `stream: true`。 |
| 502 | upstream_unavailable | 线路出错或暂时不可用。 | 稍后重试。 |
| 502 | upstream_busy | 模型方限流。模型方的 429 不会原样返回给你，而是换成这个 502。 | 稍后重试。 |
| 502 | empty_completion | 模型方返回了空内容。这不是对你的内容的判定。 | 重试。 |
| 503 | model_maintenance | 型号维护中，暂停接单，期间不会改由其他模型作答。 | 维护结束后重试，进度见 [服务状态](https://nezhagate.com/status)。 |

流式请求开始输出后再出错，状态码不会改变：错误会以一条带 `error` 的数据出现在流里，或者流直接结束（没有 `data: [DONE]`），请按中断处理。