GPT-6 Astra API 教程：使用 Responses API 构建你的第一个应用
使用 Responses API、推理控制、结构化输出、工具、对话状态和生产安全防护，构建您的第一个 GPT-6 Astra 应用。
使用GPT-6 Astra进行构建的最简洁方式是Responses API。OpenAI支持通过Chat Completions处理基础的Astra请求，但其当前模型指南指出，工具调用必须使用Responses。这使得Responses成为需要网络搜索、文件搜索、自定义函数、计算机操作、图像生成、结构化输出或多轮状态管理的新应用的实用默认选择。
本教程将构建一个小型“创意简报审阅器”。它接收一份创意简报，识别缺失的决策，并返回另一个界面可使用的结构化结果。同样的架构也适用于研究助手、编码工具和文档工作流程。
这些示例刻意保持范围狭窄。身份验证、SDK 版本发布和产品访问权限可能会发生变化，因此在部署前，请将实现细节与官方 Responses API 文档进行比对。
开始前需要准备什么
您需要一个已启用计费且能访问 gpt-6-astra 的 OpenAI API 项目。ChatGPT 订阅与 API 计费是分开的。Astra 模型页面目前未列出免费层级的 API 支持。
对于Node.js，请通过常规包管理器安装最新的OpenAI SDK，并将API密钥放置在服务端环境变量中。不要将其嵌入浏览器代码或提交到代码仓库中。
我们的第一个请求只需要三个字段：
import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.create({
model: "gpt-6-astra",
reasoning: { effort: "medium" },
输入：“审阅这份简报：一位快递员发现了一封寄给明天的信。”
});
console.log(response.output_text);
output_text 是一个便捷属性，用于收集响应中的文本。生产环境中的应用程序还应检查响应状态、错误和使用情况，而不是假设每次调用都正常完成。
理解请求结构
模型
使用精确的模型标识符 gpt-6-astra。不要猜测官方目录中未列出的别名或过时快照。
输入
输入可以是字符串或结构化内容。Astra 接受文本和图像输入。它原生生成文本；当前模型页面不支持音频和视频作为模型模态。
reasoning
reasoning.effort 字段控制模型应用的推理程度。Astra 支持 low、medium、high、xhigh 和 max。它不支持 none；OpenAI 表示该设置会返回 HTTP 400。
从中等设置开始评估。在相同任务上比较较低和较高的设置，而不是假设更多的推理总是经济的。
在下游使用结果： 一旦您的应用生成经批准的脚本或镜头简报，创作者可将其导入 Elser AI 进行角色设计、故事板制作、场景生成和编辑。这是一个工作流程交接，并非声称原生集成。
为模型提供真实输出契约
一个简单的段落很难验证。我们的审阅者应返回一个稳定的对象，其中包含摘要、缺失的决策以及简报是否准备好进行故事板制作。
使用结构化输出时，在 text.format 下定义 JSON 模式：
const briefSchema = {
type: "object",
properties: {
logline: { type: "string" },
missing_decisions: {
type: "数组",
items: { type: "string" }
},
ready_for_storyboard: { type: "boolean" }
},
必填： ["logline", "missing_decisions", "ready_for_storyboard"],
additionalProperties: false
};
const response = await client.responses.create({
model: "gpt-6-astra",
reasoning: { effort: "medium" },
instructions:
说明： [
"审查创意简报，确保其具备制作条件。",
"不要凭空编造缺失的预算、版权、受众或时长决策。"
].join(" "),
input: "一位快递员发现了一封写给明天的信。"
text: {
format: {
type: "json_schema",
name: "简要回顾",
strict: true,
schema: briefSchema
}
}
});
const review = JSON.parse(response.output_text);
模式有效性不能保证事实或创意质量。还需验证必要的业务规则。例如，当缺少运行时长、受众或版权约束时，ready_for_storyboard 应为 false。
添加自定义函数
假设已批准的字符记录存在于你的数据库中。让 Astra 请求该记录，而不是将整个目录粘贴到每个提示中。
概念上，定义一个函数工具，包含名称、描述、严格的参数模式以及执行逻辑。当响应包含函数调用时：
- 解析并验证其参数；
- 授权当前用户访问；
- 在您的应用程序中执行该函数；
- 使用原始的
call_id返回一个function_call_output； - 继续“回复”对话。
模型不会执行你的数据库函数。你的代码会执行。工具描述用于指导选择，它们不是安全边界。
GPT-6 Astra 还支持异步工具调用。在符合条件的函数或自定义工具上设置 async: true，可以让模型在您的应用程序运行工具时继续独立工作。当任务完成后，在后续的 Responses 请求中，使用原始调用 ID 发送其输出。这与后台模式不同：异步工具调用改变了模型是否等待工具结果，而后台模式则涉及响应生成本身。
维护多轮状态
如需简短跟进，请传递之前的回复ID：
const first = await client.responses.create({ model: "gpt-6-astra", reasoning: { effort: "medium" }, input: "审查这份六镜头制作简报：..." });
const revised = await client.responses.create({ model: "gpt-6-astra", previous_response_id: first.id, reasoning: { effort: "medium" }, input: "修改一则30秒竖屏视频的评论。" });
OpenAI 将 `store: true` 和之前的响应记录为一种保持状态的方式。具有不同保留要求的组织应审查可用的无状态和加密推理选项，而不是盲目复制持久化模式。
不要无限期地发送不受控制的对话历史。长上下文会增加成本，可能包含过时的指令，并可能超过 272,000 个输入令牌的高价门槛。
## 在对话中途更改推理努力程度
Astra 在标准单代理模式下支持 `configuration_update` 项。它们可以在保持请求级提示前缀以进行缓存的同时，提高或降低推理努力。
例如，以低投入开始常规审查，然后升级到故障分析：
```javascript
const next = await client.responses.create({ model: "gpt-6-astra", previous_response_id: first.id, reasoning: { effort: "低" }, input: [ { type: "configuration_update", reasoning: { effort: "high" } }, { role: "用户", content: "发现连续性故障并提出最小修复方案。" } ] });
官方推理指南指出了兼容性限制：配置更新仅适用于Astra，在标准单代理模式下生效，不能在历史记录中相邻，且不能与自动压缩或截断功能结合使用。在广泛采用之前，请先阅读当前指南。
## 谨慎添加图片
图像输入可以帮助审阅者将故事板画面与角色简介进行对比。在结构化输入中提供文本和一个`input_image`项。要求模型将可见观察与推断区分开。
例如，要求提供一份涵盖发型、配饰侧边、调色板和服装构造的清单。不要要求它从外观推断性格，也不要在图像不清晰时将微小的视觉细节视为确定无疑。
如果结果用于生产环境，请在将身份规则保存到 [Elser AI](https://www.elser.ai/) 之前，让人员审批这些规则。视觉分析可以减少审核工作，但不能替代审核。
## 处理错误与不完整响应
生产代码应处理的不只是网络故障。请检查：
- 认证和项目访问错误；
- 由于不支持的字段或推理值导致的HTTP 400错误；
- 速率限制；
- 因输出限制导致的不完整回复；
- 工具调用参数验证失败；
- 已过期的外部任务；
- 符合模式但语义上不可用的输出；
- 用户取消和时间限制。
使用带退避机制的有限重试来处理真正的瞬时故障。不要原样重试无效请求。记录请求标识符、模型、延迟时间、令牌使用情况以及工具执行结果，避免不必要地存储敏感内容。
## 使用Astra时应避免的参数
OpenAI 当前的 Astra 迁移指南指出，应移除 `temperature`、`top_p` 和 `top_logprobs`。Chat Completions 请求还应移除 `logprobs`，而 Responses 请求则应从 `include` 中省略 `message.output_text.logprobs`。
从通用API参考中复制的示例可能显示其他模型接受的字段。模型特定指南将指导您的Astra请求。
## 测试应用程序，而不仅仅是模型
创建一个包含以下内容的小型评估集：
- 完成简报；
- 缺少运行时间或观众的内裤；
- 角色细节冲突；
- 上传文档中的恶意指令；
- 一张细节模糊的图片；
- 一个应被拒绝的函数调用；
- 接近你成本边界的一个非常长的简报。
测量首次通过接受率、结构化输出有效性、不支持的声明、工具成功率、延迟时间、令牌成本和人工修正时间。对完整的工具循环进行红队测试，因为权限和外部数据会带来基础文本提示无法解决的风险。
## 从API输出到动画
样本审阅者在推理与渲染之间建立了清晰的边界。它可以返回经过验证的剧情梗概、缺失的决策以及分镜就绪状态。生产服务可以通过角色锁定、定时镜头和连续性规则来扩展该模式。
批准后，使用 [Elser AI](https://www.elser.ai/) 构建角色和分镜，生成场景素材，添加配音或音乐并完成最终剪辑。保持 API 结果的版本化，以便制作变更可追溯。
## 常见问题解答
### 我应该使用哪个API来调用GPT-6 Astra？
对于新项目和工具调用，请使用 Responses API。基本的 Chat Completions 请求受支持，但 Astra 工具调用需要使用 Responses。
### GPT-6 Astra 模型 ID 是什么？
使用 `gpt-6-astra`。
### 我可以为GPT-6 Astra设置温度吗？
OpenAI当前的迁移指南建议移除`temperature`、`top_p`和`top_logprobs`。
### GPT-6 Astra 是否支持 JSON 输出？
是的。支持结构化输出。请定义并验证合适的 JSON 模式，而不是依赖非正式的格式指令。
### GPT-6 Astra 能调用我的应用程序函数吗？
是的。模型可以请求调用函数，但您的应用程序负责验证权限、执行代码并返回结果。
### GPT-6 Astra 在 API 免费套餐中可用吗？
当前模型页面将免费套餐列为不支持。
## 结论
一个可靠的GPT-6 Astra应用始于Responses API、明确的推理设置以及你的软件能够验证的输出契约。仅在获得授权和可观测性的前提下添加工具，保持对话状态有界，并像对待理想输入一样仔细测试失败情况。
对于创意系统，使用Astra使简报精确且可审查。然后将已接受的脚本和镜头数据传输到[Elser AI](https://www.elser.ai/)进行视觉制作。
## 官方来源
- [GPT-6 Astra 模型页面](https://developers.openai.com/api/docs/models/gpt-6-astra)
- [GPT-6 Astra 模型指南](https://developers.openai.com/api/docs/guides/latest-model)
- [迁移至响应 API](https://developers.openai.com/api/docs/guides/migrate-to-responses)
- [异步工具调用](https://developers.openai.com/api/docs/guides/async-tool-calling)
- [推理模型](https://developers.openai.com/api/docs/guides/reasoning)
*技术细节已于2026年9月4日根据OpenAI官方文档核实。在生产环境使用前，请针对当前SDK测试示例。*
