GPT-6 Astra API 怎么调用？2026 Python 从 API Key 到第一次请求完整教程

OpenAI 在 2026 年 9 月 3 日公布 GPT-6 Astra，API 标识为 gpt-6-astra，4 日对 API 客户开放。很多人搜「怎么调用」，不是因为不知道它贵或上下文有 105 万，而是卡在更土的地方：ChatGPT 里已经能看到 GPT-6 Pro，Python 却报 model_not_found；或者把去年的 Chat Completions 示例原样粘贴，一加 tools 就 400。本文不重复「Astra 是什么」——那篇见站内 发布时间、价格与 Agent 解析——只把你从 API Key 带到第一次成功的 output_text。

为什么第一次请求经常失败

旧方式是：旗舰一出，把脚本里的模型字符串改成「最新那个」。新方式是：先对齐四件事——付费项目、环境变量里的 Key、端点、钉死的模型 ID 与 effort。分水岭不是你会不会写 OpenAI()，而是你有没有把 ChatGPT 窗口和 API 项目当成两个系统。

最常见的五条失败路径彼此无关，却经常叠在一起。第一，Plus / Pro 能聊 GPT-6 Pro，并不等于 platform.openai.com 的项目已经开通 Astra。第二，企业工作区默认关闭该模型，管理员没开开关时，SDK 报的不是「去找管理员」，而是模型不可用。第三，免费 API 档明确不支持 Astra，充值或升级用量档之前不要怀疑 SDK。第四，官方当前指引是：纯文本还可以走 Chat Completions，工具调用必须走 Responses。第五，有人把 Key 写进脚本、提交到 Git，或者用聊天记录里的截图当密钥，轮换后旧请求会突然 401。

知识截止为 2026 年 4 月 30 日。推理强度 reasoning.effort 支持 low、medium、high、xhigh、max，不支持 none，乱写会 400。网关默认常为 low。第一次探测就用 low：你要验证的是通路，不是把 max 推理费烧在「hello」上。

先分类：Key、端点、模型 ID

把你听到的名字拆成四层，避免把「我已经登录 ChatGPT」当成「我已经能打 API」。

拿 Key 的最短路径：打开 platform.openai.com，确认当前组织与项目已开通计费，不是免费档；进入 API keys 创建一把只给本机或本 CI 用的密钥；立刻复制一次，之后界面不再回显完整值。Windows 用系统环境变量或密钥管理器，macOS / Linux 用 export。不要把 Key 发给同事聊天窗口，也不要写进 Jupyter 的默认输出。

# macOS / Linux
export OPENAI_API_KEY="sk-..."

# never commit the key
echo 'OPENAI_API_KEY=sk-...' >> .env
echo '.env' >> .gitignore

SDK 用官方 openai 包。版本过旧时，client.responses 可能根本不存在，看起来像「Astra 没开」，其实是你还在用 Completions-only 的旧客户端。

python3 -m pip install -U "openai>=1.0"
python3 -c "import openai; print(openai.__version__)"

模态上，上线时支持文本和图像输入、文本输出；音频和视频输入未开放。Responses 工具包括网页搜索、文件搜索、图像生成、代码解释器、托管 shell、apply patch、Skills、Computer Use、MCP 和 tool search。支持函数调用与结构化输出，不支持微调。这些能力都建立在「第一条文本请求已经成功」之上，不要第一步就接 Computer Use。

Responses 和 Chat Completions 怎么选

非对称结论先写在这：纯文本两条路都能打 Astra；只要出现工具、托管能力和异步 tool，就必须走 Responses。 不要为了「我熟悉 messages 数组」把整个 Agent 焊死在 Completions 上。

价格仍是每百万 token 输入 10 美元、输出 50 美元；缓存读 1 美元、缓存写 12.50 美元。上下文 1,050,000，最大输出 128,000。输入超过 272K，整单按 2× 输入与缓存、1.5× 输出计。Fast 为适用费率的两倍。搜索和 Computer Use 另收工具费。第一次请求用一句话、low effort，账单应接近「可以忽略」；若第一次就烧出长推理，是你把探测写成了评测。

工具循环的协议层没有变：模型产出结构化请求，运行时执行副作用。若你还在把三家 JSON 方言写进业务 if-else，先把内部 ToolCall 收拢。细节见 Function Calling 协议对照。和 Gemini、上一代 GPT 的分流，可参考 Gemini 4 vs GPT-5.6。

最小 Python：从 Key 到第一次请求

下面这条请求只做三件事：读环境变量、钉死 gpt-6-astra、用 low effort 换一句确认。成功标准不是文采，而是你能打印 output_text 和 response.id。把 ID 留下，排障时比「我刚才好像成功了」有用。

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    instructions="You are a concise engineering assistant.",
    input="Reply with one sentence: Astra API is reachable.",
    reasoning={"effort": "low"},
)

print(response.output_text)
print(response.id)
print(getattr(response, "usage", None))

若组织规定存量网关只能打 Chat Completions，文本探测可以先走这条。它能证明 Key 和模型 ID 通了，不能证明你以后能接 hosted shell。

from openai import OpenAI

client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[
        {"role": "system", "content": "You are a concise engineering assistant."},
        {"role": "user", "content": "Reply with one sentence: Astra API is reachable."},
    ],
)

print(completion.choices[0].message.content)

流式是可选的第二步，不是第一课。先保证非流式成功，再打开 stream=True。事件类型以你安装的 SDK 为准；下面按常见的 response.output_text.delta 读取增量。若字段名有出入，打印 event.type 对照官方事件表，不要猜。

from openai import OpenAI

client = OpenAI()

stream = client.responses.create(
    model="gpt-6-astra",
    input="List three safe checks before a production cutover.",
    reasoning={"effort": "low"},
    stream=True,
)

for event in stream:
    if getattr(event, "type", "") == "response.output_text.delta":
        print(event.delta, end="", flush=True)

错误不要一律重试。连接失败才看网络和代理；429 先看 Retry-After 和用量档；400 多半是模型 ID、effort 或 schema 写错，重试一万次也不会好。401 / 403 回到项目开关和 Key 范围。免费档或企业未放行时，不要在应用层写「自动换一个模型」——那会把生产静默切回旧旗舰。

from openai import APIConnectionError, APIStatusError, OpenAI, RateLimitError

client = OpenAI()

try:
    client.responses.create(
        model="gpt-6-astra",
        input="ping",
        reasoning={"effort": "low"},
    )
except APIConnectionError as exc:
    print("network", exc)
except RateLimitError as exc:
    print("rate_limit", exc)
except APIStatusError as exc:
    print(exc.status_code, exc.message)

场景怎么选

推荐组合

A — 个人开发者： 本机环境变量 + openai SDK + Responses 最小脚本。默认 low。只有这条通路连续成功，再打开流式。密钥与 ChatGPT 登录态分开。日常补全仍可走更便宜的模型，Astra 留给探测失败重试和长任务。

B — 小团队网关： 项目级 Key，CI 用独立只读密钥。配置中心锁定 gpt-6-astra 与快照，禁止隐式跟随「最新旗舰」。聊天走便宜模型，编码与 computer-use 走 Astra。工具循环的 JSON 协议先收拢，再接托管工具。

C — 企业： 管理员先开工作区开关；合格客户再谈零数据保留。预算告警按项目。长提示强制缓存前缀，并盯住 272K 整单升档。会写磁盘的会话放到可销毁的远程 Mac，权限白名单。账户与交付边界看 帮助中心，算节点月费看 Mac mini 定价。

常见误区

1. 以为 ChatGPT 里出现 GPT-6 Pro 就等于 API 已开通。
2. 把 Key 写进源码、笔记本输出或群聊，然后怪模型「不稳定」。
3. 第一次请求就 effort=max 或塞进半个仓库，触发长推理和 272K 升档。
4. 新工具链继续焊在 Chat Completions 上，直到 hosted shell 全部 400。
5. 模型字符串写成 gpt-6、chatgpt-6 或传闻中的 Ultra。

落地步骤：7 步

1. 确认 API 项目已开通计费，且不是免费档；企业找管理员打开 Astra。
2. 在平台创建 Key，只写入环境变量或密钥管理器，加入 .gitignore。
3. 安装当前 openai SDK，确认存在 client.responses.create。
4. 用 Responses 发送 model="gpt-6-astra"、reasoning.effort="low" 的一句话请求。
5. 打印 output_text、response.id 和 usage；保存 ID 方便对账。
6. 文本通路稳定后，再加流式或工具；工具协议对照站内 Function Calling 文。
7. 会改文件、跑命令、开浏览器的会话放到隔离 远程 Mac，会话结束销毁。

FAQ

ChatGPT 里已经有 GPT-6 Pro，为什么 Python 还是调不通？

ChatGPT 订阅和 API 是两套账单与准入。企业工作区默认关闭 Astra，免费 API 档不支持该模型。到 platform.openai.com 的付费项目里建 Key。

第一次请求该用 Responses 还是 Chat Completions？

纯文本两条都能打 gpt-6-astra。新项目默认 Responses。函数调用、托管工具、结构化输出与异步工具必须走 Responses。

模型 ID 到底写什么？

写 gpt-6-astra。生产再锁官方目录里的日期快照。不要猜 gpt-6、chatgpt-6 或未公布的 Ultra。

reasoning.effort 可以设 none 吗？

不行。Astra 支持 low、medium、high、xhigh、max。none 会 400。第一次探测用 low。

Key 应该写在脚本里吗？

不应该。只用环境变量或密钥管理器，禁止提交到 Git。轮换时旧 Key 立刻作废。

总结

调用 GPT-6 Astra 的第一课不是崇拜旗舰，而是把四件事对齐：付费项目、环境变量里的 Key、Responses（或你被迫使用的 Completions 文本通路）、以及钉死的 gpt-6-astra。第一次请求用一句话和 low effort，能打印 output_text 才算通路成立。工具、长上下文和 Computer Use 是下一课，而且必须落在可销毁的执行环境上。需要稳定的远程 Mac 时，从 租用页 和 定价页 看节点，账户问题走 帮助中心。

延伸阅读

• GPT-6 Astra 是什么：发布、价格与 Agent →
• Function Calling 与 JSON 工具协议 →
• Gemini 4 vs GPT-5.6 开发者怎么选 →