OpenAI API 快速开始

本指南帮助你在 5 分钟内完成 OpenAI API 的第一次调用。

如果这是你第一次接 AI API，把它当成“先让电灯泡亮起来”的教程：
先求跑通，不求完美；先拿到稳定输出，再谈复杂架构。

#准备工作

#1. 获取 API Key

1. 访问 OpenAI Platform↗
2. 注册或登录账号
3. 进入 API Keys↗ 页面
4. 点击 "Create new secret key"
5. 复制并安全保存 Key

⚠️ 重要：API Key 只显示一次，请立即保存！

#读者任务目标

• 目标 1：成功跑出一次 API 响应
• 目标 2：知道如何安全保存密钥
• 目标 3：知道如何选择第一个默认模型

#2. 设置环境变量

bash复制
# macOS / Linux
export OPENAI_API_KEY="sk-..."

# Windows PowerShell
$env:OPENAI_API_KEY="sk-..."

# 或在 .env 文件中
OPENAI_API_KEY=sk-...

#Python 快速开始

#安装

bash复制
pip install openai

#第一次调用

python复制
from openai import OpenAI

client = OpenAI()  # 自动读取环境变量中的 API Key

response = client.responses.create(
    model="gpt-5.2",
    input="用一句话介绍人工智能"
)

print(response.output_text)

#运行结果

人工智能是让计算机模拟人类智能行为的技术，包括学习、推理和解决问题的能力。

#Node.js 快速开始

#安装

bash复制
npm install openai

#第一次调用

typescript复制
import OpenAI from 'openai';

const client = new OpenAI();  // 自动读取环境变量

async function main() {
  const response = await client.responses.create({
    model: 'gpt-5.2',
    input: '用一句话介绍人工智能'
  });

  console.log(response.output_text);
}

main();

#使用 curl

不想安装 SDK？可以直接用 curl：

bash复制
curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.2",
    "input": "用一句话介绍人工智能"
  }'

#核心概念

#Messages 结构

python复制
input = [
    {"role": "system", "content": "你是一个专业的程序员"},  # 系统提示
    {"role": "user", "content": "什么是 API？"},           # 用户消息
    {"role": "assistant", "content": "API 是..."},        # 助手回复
    {"role": "user", "content": "给个例子"}               # 继续对话
]

#角色说明

#常用参数

python复制
response = client.responses.create(
    model="gpt-5.2",           # 模型选择
    input=[...],               # 对话内容
    max_output_tokens=1000,    # 最大输出长度
    temperature=0.7            # 创造性 (0-2)
)

#temperature 参数

0.0 - 最确定，适合代码/数学
0.7 - 平衡，适合一般对话
1.0+ - 更有创意，适合写作/创意

一个好记类比：  
`temperature` 像“让助手自由发挥的程度”。  
越低越像按 SOP 执行，越高越像头脑风暴会议。

#模型选择

#推荐模型

#代码示例

python复制
# 日常使用
model = "gpt-5.2"

# 预算敏感
model = "gpt-5-mini"

# 需要稳定性
model = "gpt-5.1"

#完整示例

#简单问答

python复制
from openai import OpenAI

client = OpenAI()

def ask(question: str) -> str:
    response = client.responses.create(
        model="gpt-5.2",
        input=question
    )
    return response.output_text

# 使用
answer = ask("Python 和 JavaScript 的主要区别是什么？")
print(answer)

#带系统提示

python复制
def ask_expert(question: str, expertise: str) -> str:
    response = client.responses.create(
        model="gpt-5.2",
        input=[
            {"role": "system", "content": f"你是一位{expertise}专家，用简洁专业的语言回答问题。"},
            {"role": "user", "content": question}
        ]
    )
    return response.output_text

# 使用
answer = ask_expert(
    "如何优化 React 应用性能？",
    "前端开发"
)

#多轮对话

python复制
class ChatBot:
    def __init__(self, system_prompt: str = None):
        self.client = OpenAI()
        self.messages = []
        if system_prompt:
            self.messages.append({"role": "system", "content": system_prompt})

    def chat(self, user_input: str) -> str:
        self.messages.append({"role": "user", "content": user_input})

        response = self.client.responses.create(
            model="gpt-5.2",
            input=self.messages
        )

        assistant_message = response.output_text
        self.messages.append({"role": "assistant", "content": assistant_message})

        return assistant_message

# 使用
bot = ChatBot("你是一个友好的编程助手")
print(bot.chat("你好"))
print(bot.chat("Python 怎么读文件？"))
print(bot.chat("那写文件呢？"))  # 记住上下文

#错误处理

python复制
from openai import OpenAI, APIError, RateLimitError, AuthenticationError

client = OpenAI()

try:
    response = client.responses.create(
        model="gpt-5.2",
        input="Hello"
    )
except AuthenticationError:
    print("API Key 无效")
except RateLimitError:
    print("请求太频繁，请稍后重试")
except APIError as e:
    print(f"API 错误: {e}")

#新手最常踩的坑

• 在前端代码里直接写 API Key（高风险）
• 一上来就用最贵模型，忘了先做效果基线
• 没有记录请求输入输出，出问题时无法复盘

#费用监控

python复制
response = client.responses.create(...)

# 查看 token 使用
usage = response.usage
print(f"输入 tokens: {usage.prompt_tokens}")
print(f"输出 tokens: {usage.completion_tokens}")
print(f"总计 tokens: {usage.total_tokens}")

# 估算费用：请以官方 Pricing 为准
# https://platform.openai.com/pricing

#下一步

• 流式响应 - 实时输出
• Function Calling - 函数调用
• Embeddings - 文本向量化

---

提示：建议先在 OpenAI Playground↗ 测试，再写代码。