OpenAI API

是什么，为什么存在

OpenAI API 是 OpenAI 托管模型的编程接口。对于新的文本生成应用，核心入口是 POST /v1/responses；Python SDK 对应 OpenAI().responses.create(...)。一次请求可以包含文本、图像或文件输入，也可以声明内置工具和自定义函数工具。

Responses API 解决的不只是“把提示词发给模型”。它提供统一的响应对象，里面包含状态、类型化输出项、用量和错误信息。应用因此可以明确区分文本、推理项、工具调用与其他输出，而不是把所有结果压成一个无法检查的字符串。

顶层 output 是 响应项（response item） 数组，不保证第一个元素就是助手文本。官方 SDK 提供 output_text 便利属性，用来聚合响应中的文本输出；需要处理工具、引用或其他内容时，仍要遍历类型化输出项。

API 也提供两种 对话状态（conversation state） 管理方式。应用可以把上一轮 response.id 作为 previous_response_id 继续，也可以使用持久的 Conversation 对象。无论选择哪种方式，应用仍负责租户隔离、保留策略、上下文预算和业务历史。

这个主题聚焦 Responses API 的基础协议以及可靠的应用边界。提示词设计、结构化输出、函数调用、智能体和可观测性各有独立主题；这里不会重复它们的完整教程。图像生成、音频、嵌入和旧 Assistants API 也不属于这条最小调用链。

调用前需要创建项目密钥，并通过 OPENAI_API_KEY 或秘密管理服务注入服务端进程。浏览器和移动应用不能持有长期 API 密钥；它们应调用你自己的后端，由后端执行认证、授权、限额和 OpenAI 请求。

后端也不应把整个 Responses API 原样代理给客户端。模型、工具、输出预算和可用参数应由服务端允许列表控制，否则攻击者可以借你的项目权限调用更昂贵的能力或访问不该开放的工具。

工作原理

一个最小请求包含 model 与 input。instructions 用于可信的高层行为约束，input 用于本轮用户内容或类型化输入项。直接发送 HTTP 时还要带上 Authorization: Bearer ... 和 Content-Type: application/json；官方 SDK 会处理认证头、序列化和错误类型。

model 是部署选择，不是业务逻辑。开发环境可以使用当前别名进行探索，但生产发布应根据可用性与评测结果选择模型，并在需要稳定行为时固定模型快照。任何模型或提示词变更都要重新运行同一套评测，而不是根据名称推断兼容性。

同步响应可能处于 completed、failed、in_progress、cancelled、queued 或 incomplete 等状态。只有状态符合应用契约时，才能接受内容；达到输出上限等不完整情况必须读取 incomplete_details 并走显式回退。文本读起来像完整句子，不能证明响应已经完整结束。

这些状态只说明服务端生成生命周期，不会替应用判断内容是否正确。completed 之后仍要验证结构、领域规则和权限；incomplete 也不一定适合重试，例如输入或输出预算配置错误时，原样重发只会重复失败。

output 中每个元素都有 type。消息项还包含自己的 content 数组，其中的文本块类型为 output_text。推理模型或启用工具的请求可能在消息项前后产生其他类型，因此直接读取 response.output[0].content[0].text 是脆弱的。

多轮交互可以通过 previous_response_id 建立响应链。继续请求仍应显式发送本轮的 instructions，因为上一轮的 instructions 不会自动带到下一轮。响应链也不会免除上下文成本：链中先前输入仍计入后续请求的输入 token。

设置 stream: true 后，服务通过 服务器发送事件（Server-Sent Events，SSE） 逐步返回状态和增量。常见文本事件包括 response.created、多次 response.output_text.delta、最终的 response.completed，以及 error。客户端必须看到终止事件后，才能把已显示的部分文本标为完成。

下面是一次普通调用与两种后续路径。模型输出在进入业务代码前仍是不可信数据；模式验证、授权和副作用控制都位于 API 边界之外。

可靠实现会在一次调用周围记录四类信息：应用功能和提示词版本、所请求与实际返回的模型、服务商的 请求 ID（request ID） 、完成状态与验证结果。日志应使用字段允许列表并删减敏感内容；能够关联请求不等于保存完整提示词、用户文件或认证头。

示例

以下四个示例都在本地运行，不向 OpenAI 发送请求，也不把手写内容冒充真实模型输出。它们使用与已验证文档一致的请求或响应夹具，测试应用自己拥有的协议代码；接入测试仍需使用受限的独立项目和测试密钥。

按类型读取响应项

第二个示例故意让推理项排在消息项之前。解析器先检查顶层状态，再遍历全部消息与内容块；它不会假定 output[0] 一定含有 content。

def completed_text(response: dict) -> str:
    if response["status"] != "completed":
        detail = response.get("incomplete_details") or response.get("error")
        raise RuntimeError(f"response not completed: {detail}")

    pieces = []
    for item in response["output"]:
        if item.get("type") != "message":
            continue
        for block in item.get("content", []):
            if block.get("type") == "output_text":
                pieces.append(block["text"])
    return "".join(pieces)


response = {
    "id": "resp_demo",
    "status": "completed",
    "output": [
        {"type": "reasoning", "id": "rs_demo", "summary": []},
        {
            "type": "message",
            "role": "assistant",
            "content": [
                {"type": "output_text", "text": "billing", "annotations": []}
            ],
        },
    ],
    "usage": {"input_tokens": 28, "output_tokens": 7, "total_tokens": 35},
}

print("Status:", response["status"])
print("Text:", completed_text(response))
print("Total tokens:", response["usage"]["total_tokens"])

Status: completed
Text: billing
Total tokens: 35

示例中的响应和 token 数都是本地协议夹具，不是实时模型结果或容量数据。使用官方 SDK 时，纯文本路径可以先检查状态，再读取 response.output_text；需要工具调用、引用或其他输出时，则按类型遍历 response.output。未知类型应安全记录或拒绝，不能当作文本强制解析。

构造对话续接请求

第三个示例生成第二轮请求的 JSON。它显式携带上一轮 ID，也重新发送可信指令；如果产品改用了不同的系统规则，这个边界能让变化出现在请求构造器和测试中。

import json


def next_turn(previous_id: str, user_input: str) -> dict:
    return {
        "model": "gpt-6-astra",
        "previous_response_id": previous_id,
        # 上一轮 instructions 不会自动继承。
        "instructions": "Answer as a concise support agent.",
        "input": [{"role": "user", "content": user_input}],
        "store": True,
    }


request_body = next_turn(
    "resp_first",
    "Explain why the ticket belongs in billing.",
)
print("Previous:", request_body["previous_response_id"])
print("Instructions:", request_body["instructions"])
print("Role:", request_body["input"][0]["role"])
print("Stored:", request_body["store"])
print(json.dumps(request_body["input"][0], sort_keys=True))

Previous: resp_first
Instructions: Answer as a concise support agent.
Role: user
Stored: True
{"content": "Explain why the ticket belongs in billing.", "role": "user"}

previous_response_id 让服务找到需要继续的响应链，但应用仍要确认这个 ID 属于当前租户和当前业务会话。若数据策略不允许默认保存响应，就应评估 store: false 与手动传递上下文的方式；Conversation 对象具有不同的持久化生命周期，也不能在没有保留策略的情况下默认使用。

对话变长时，不能仅靠删除最早字符串来管理上下文。工具调用与结果、消息角色和关键业务事实都可能形成协议依赖。应制定可测试的拒绝、摘要、压缩或重新开始策略，并记录哪一种策略影响了本轮请求。

累积流式文本

最后一个示例把 SSE 解码后的事件作为夹具输入状态机。只有收到 response.completed 才返回文本；显式错误、失败状态或没有终止事件的连接都会产生异常。

def collect_stream(events: list[dict]) -> str:
    pieces = []
    completed = False
    for event in events:
        event_type = event["type"]
        if event_type == "response.output_text.delta":
            pieces.append(event["delta"])
        elif event_type == "response.completed":
            completed = event["response"]["status"] == "completed"
        elif event_type in {"response.failed", "response.incomplete", "error"}:
            raise RuntimeError(event_type)
        # 其他生命周期事件不表示文本已经完成。
    if not completed:
        raise RuntimeError("stream ended before response.completed")
    return "".join(pieces)


events = [
    {"type": "response.created", "response": {"status": "in_progress"}},
    {"type": "response.output_text.delta", "delta": "Payment "},
    {"type": "response.output_text.delta", "delta": "issue"},
    {"type": "future.event", "data": {}},
    {"type": "response.completed", "response": {"status": "completed"}},
]

print("Text:", collect_stream(events))
print("Terminal event:", events[-1]["type"])

Text: Payment issue
Terminal event: response.completed

真实 SDK 返回类型化事件，直接消费 HTTP 时则要先正确解析 SSE 帧。UI 可以立即显示增量，但在终止事件前应保持“生成中”状态。连接中断后重新请求会开始一次新的生成，不能把新输出直接拼到旧的部分文本后，伪装成同一条完整响应。

陷阱

在不可信客户端放置 API 密钥

修复： 只在受控的服务端运行时注入密钥，并通过自己的后端暴露窄接口。按环境和项目分离密钥，限制权限与支出，记录使用情况；发现泄露后立即撤销并轮换，而不是只从 Git 历史中删除字符串。

把 output[0] 当作文本

修复： 纯文本路径使用 SDK 的 output_text 聚合属性；协议级代码按 type 遍历所有输出项和内容块。先检查顶层状态，再决定是接受文本、继续工具循环、报告截断还是回退。

误以为续接会继承所有设置

修复： 每轮从版本化配置重建可信指令，并用多轮契约测试检查实际请求。验证上一轮 ID 的租户与会话归属，同时把响应保存期限、Conversation 生命周期和上下文成本纳入设计。

对所有 429 和 4xx 原样重试

修复： 按 HTTP 状态、error.type 和 error.code 分类。暂时性限流优先遵守 Retry-After，缺失时才使用带随机抖动的有界指数退避；配置、认证、余额与业务验证错误应快速失败并交给相应处置流程。

把模型重试扩大为业务重放

修复： 把模型响应、验证和业务提交拆成可恢复的状态转换。副作用使用持久化的 幂等键（idempotency key） 与结果记录；超时后先查询既有结果，再判断是否需要重新执行。

把流断开当作正常完成

修复： 按事件类型维护状态，只有明确的完成事件才能提交结果。断流时保留诊断信息并把部分文本标为未完成；若重新生成，应替换或单独展示新结果，不能无条件续接旧字符串。

延伸阅读

• OpenAI API 参考：创建模型响应
• OpenAI API 文档：文本生成
• OpenAI API 文档：对话状态
• OpenAI API 文档：流式响应
• OpenAI API 文档：错误码
• OpenAI API 文档：生产最佳实践