OpenAI Platform 快速上手：从密钥到第一次 Responses API 调用

OpenAI Platform 是调用 OpenAI 模型能力的开发者入口：你在平台上创建 API 密钥，通过 HTTP 接口或官方 SDK 把文本生成、结构化输出、图像、语音、嵌入等能力接进自己的应用。它适合需要把模型能力嵌入产品、脚本或内部工具的开发者，而不是只想在聊天界面里对话的普通用户。平台的核心接口是 Responses API，围绕它还有模型目录、工具调用、会话状态、流式输出、批处理与成本控制等一整套配套能力。本文按「准备—调用—跑通—避坑」的顺序，把第一次接入需要知道的东西讲清楚。如果你更习惯先看工具页再动手，可以从 OpenAI Platform 进入。

准备工作

账号与组织

使用 API 需要一个 OpenAI Platform 账号，并在平台上建立或加入一个组织（Organization）。组织之下可以划分项目（Project），API 密钥、用量与花费通常按项目维度管理。团队协作时，建议按用途拆分项目，例如开发、测试、生产各一个，这样密钥泄露或误用时影响范围可控，账单也更容易归因。

平台提供项目与访问控制相关的配置，包括服务账号（Service accounts）、权限（Permissions）以及模型、工具与数据控制（Model, tool, and data controls）。这些属于上线前要处理的事情，第一次跑通示例时可以先不配置，但要知道它们存在。

API 密钥

在平台控制台创建 API 密钥。密钥只在创建时完整显示一次，之后无法再次查看，务必立即保存到安全的位置。不要把密钥写进前端代码、提交到版本库，或放进会被公开的配置文件。推荐的做法是通过环境变量注入：

export OPENAI_API_KEY="你的密钥"

官方 SDK 默认会读取名为 OPENAI_API_KEY 的环境变量，因此设置好之后代码里不需要再显式传参。如果使用多个项目，可以再设置组织或项目标识，让请求归属到正确的项目。

安装 SDK

平台提供多种语言的官方 SDK，也提供命令行工具 OpenAI CLI。以 Python 为例，用 pip 安装：

pip install openai

Node.js 环境则通过 npm 安装对应的包。SDK 封装了鉴权、重试、超时、流式解析等细节，比直接拼 HTTP 请求省事，建议优先使用。若你的运行环境不方便装包，也可以直接对接口发 HTTP 请求，请求体格式与 SDK 一致。

确认模型可用性

调用前先确认你要用的模型在你的账号下可用。平台的模型目录（Model catalog）列出了可选模型及其能力差异，模型选择（Model selection）页面则给出如何按任务挑模型的建议。不同模型在上下文长度、支持的输入类型、是否支持工具调用与结构化输出上并不相同，选错模型往往表现为请求被拒绝或输出格式不符合预期。价格与可用模型会调整，具体以平台当前公布的信息为准。

操作步骤

第一步：发起一次最小请求

Responses API 是平台的主接口。一次最基本的调用只需要模型名和输入内容：

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="你的模型名",
    input="用一句话解释什么是向量数据库。"
)

print(response.output_text)

这里有两个关键点。第一，参数叫 input，而不是旧接口里的 messages；它既可以是一个字符串，也可以是消息列表。第二，读取结果用 output_text 这个便捷属性，它会把你需要的文本从完整的输出结构里取出来。

第二步：理解响应结构

完整响应不只是文本。它包含一个 output 数组，数组里的每一项是一个输出条目（item），条目有类型区分：模型生成的文本是一个条目，模型发起的工具调用是另一个条目。文本条目内部还有内容块（content part），内容块同样带类型。这种分层结构是为了让「模型说了什么」和「模型要调用什么工具」能被程序区分处理。

因此，简单场景用 output_text 就够了；需要处理工具调用、多段输出或需要保留完整对话记录时，就要遍历 output 数组，按条目类型分别处理。响应里还带有用量信息，可用于统计 token 消耗。

第三步：用消息列表组织输入

当输入不止一句话时，把 input 写成消息列表，每条消息标明角色与内容：

response = client.responses.create(
    model="你的模型名",
    input=[
        {"role": "developer", "content": "你是一名严谨的技术文档编辑，回答简洁。"},
        {"role": "user", "content": "解释一下什么是幂等性。"}
    ]
)

角色用于区分指令来源与用户输入。把系统级的行为约束放在开发者角色里，把用户的实际问题放在用户角色里，是组织提示词的常见做法。提示词怎么写、如何做提示工程，平台有单独的文档与最佳实践，这里不展开。

第四步：控制输出长度与采样

请求里可以设置输出长度上限等生成参数，避免模型输出过长导致费用与延迟上升。不同模型支持的参数集合不完全一致，部分模型对采样类参数有额外限制，遇到参数不被接受时，先查该模型的说明再调整。不要凭经验假设某个参数在所有模型上都生效。

第五步：开启流式输出

面向用户的界面通常需要边生成边显示。Responses API 支持流式返回，开启后响应以事件流的形式逐步到达，你需要按事件类型增量拼接文本：

stream = client.responses.create(
    model="你的模型名",
    input="写一段 100 字左右的产品介绍。",
    stream=True
)

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

流式模式下不要再用 output_text 取最终结果，而要在事件循环里累积增量。事件类型不止文本增量一种，还有响应开始、条目添加、响应完成等，做完整实现时应覆盖这些类型，以便在结束时拿到完整响应对象。

第六步：管理对话状态

多轮对话有两种做法。第一种是自己维护历史：把上一轮的输入和模型输出都追加进 input 列表，每次请求带上完整历史。第二种是使用平台提供的会话状态能力，把上一轮响应的标识传给下一次请求，由服务端关联上下文，客户端不必重复发送全部历史。后者能减少请求体积，但需要你保存并正确传递响应标识。两种方式各有取舍，长对话、上下文接近上限时尤其要留意 token 消耗，平台提供计数 token 的方法，可在发送前估算。

第七步：处理错误与重试

平台文档列出了错误码的含义。常见情况包括鉴权失败（密钥无效或未正确加载）、请求参数不合法、超出速率限制、服务端临时故障。SDK 对部分可重试的错误会自动重试，但业务代码仍应捕获异常并给出可读的提示。遇到速率限制时，应结合平台的速率限制与花费限制配置做退避，而不是无脑循环重试。

一个完整示例

下面把前面的步骤串起来：读取环境变量中的密钥，发起一次带开发者指令的请求，打印文本结果与 token 用量，并对异常做基本处理。

import os
from openai import OpenAI, APIError, RateLimitError

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

def ask(question: str) -> str:
    try:
        response = client.responses.create(
            model="你的模型名",
            input=[
                {"role": "developer", "content": "你是技术文档助手，回答控制在三句话以内。"},
                {"role": "user", "content": question}
            ]
        )
    except RateLimitError:
        return "请求过于频繁，请稍后再试。"
    except APIError as e:
        return f"调用失败：{e}"

    usage = response.usage
    print(f"输入 token: {usage.input_tokens}, 输出 token: {usage.output_tokens}")
    return response.output_text

if __name__ == "__main__":
    print(ask("Responses API 和聊天补全接口有什么区别？"))

运行前确认三件事：环境变量已设置、模型名替换为你账号下可用的模型、依赖已安装。如果返回鉴权错误，先检查密钥是否被正确加载；如果返回模型不存在或无权访问，检查模型名拼写与账号权限；如果返回参数错误，对照该模型的参数说明逐项核对。

这个示例只覆盖文本生成。要接入工具调用，需要在请求里声明可用工具，并在响应中识别工具调用条目、执行本地逻辑后把结果回传；要处理文件输入，需要按平台支持的方式上传或引用文件；要做批量离线任务，可以走批处理接口而不是逐条同步调用。这些都属于跑通第一次调用之后的下一步。

注意事项

• 密钥安全：密钥只在创建时显示一次，泄露后应立即在控制台撤销并重建。不要把密钥放进客户端代码或公开仓库。
• 用量与花费：平台提供速率限制与花费限制配置，建议在开发阶段就设置上限，避免循环调用或异常重试造成意外支出。具体配额与价格以平台当前信息为准。
• 模型差异：不同模型支持的参数、输入类型与能力不同，跨模型迁移代码时要逐项验证，不要假设参数通用。
• 上下文长度：自行维护对话历史时，历史会随轮次增长并计入 token，长对话需要裁剪或改用会话状态能力。
• 流式处理：流式模式下结果是增量事件，必须自行拼接；同时要处理连接中断等异常，避免界面卡在中间状态。
• 地区可用性：平台文档维护了支持的国家与地区列表，接入前应确认你的部署位置在支持范围内。
• 接口演进：平台会发布变更日志与弃用说明，旧接口可能进入维护或迁移状态，长期项目应关注这些公告并预留迁移时间。
• 数据与合规：平台提供数据处理与安全相关的配置与说明，涉及敏感数据的场景应先阅读相关条款再决定是否接入。

把上面这些走一遍，你就完成了从创建密钥到第一次成功调用、再到处理多轮与流式输出的完整链路。接下来按实际业务选择模型、设计提示词、接入工具与评估流程即可。