OpenAI API 简介

OpenAI API 是最广泛使用的 AI API 之一，提供 GPT-5.2/5.1/5 系列、多模态、图像与语音模型的访问。本指南将帮助你快速上手 OpenAI API 开发。

把 OpenAI API 想成“模型操作系统”：
你可以接文字、图像、语音等不同能力，但最终拼成什么产品，取决于你的流程设计与提示词质量。

#为什么使用 OpenAI API？

#1. 强大的模型能力

#2. 完善的开发体验

• 官方 SDK (Python, Node.js)
• 详细的文档和示例
• 活跃的开发者社区
• 稳定的服务质量

#3. 灵活的计费方式

按使用量付费，无最低消费。具体价格会随模型与地区调整，请以 官方 Pricing↗ 为准。

#这页适合谁？

• 想从 0 到 1 接入 AI 能力的后端/全栈开发者
• 想把“Demo 对话”变成“可上线功能”的产品工程团队
• 想控制效果、延迟、成本三者平衡的技术负责人

#读者导向：先看哪部分

1. 新手：先看“快速开始 + 核心 API”跑通第一个请求。
2. 进阶：看“最佳实践”把安全、错误处理、流式输出补齐。
3. 负责人：看“常见问题 + 模型选择”，制定团队默认模板。

#快速开始

#1. 获取 API Key

1. 注册 OpenAI 账号↗
2. 访问 API Keys 页面↗
3. 点击 "Create new secret key"
4. 保存好你的 API Key

安全提示：API Key 只显示一次，请妥善保存。永远不要在前端代码中暴露 API Key。

#2. 安装 SDK

Python:

bash复制
pip install openai

Node.js:

bash复制
npm install openai

#3. 第一次调用

Python 示例:

python复制
from openai import OpenAI

client = OpenAI(api_key="your-api-key")

response = client.responses.create(
    model="gpt-5.2",
    input=[
        {"role": "system", "content": "你是一个有帮助的助手。"},
        {"role": "user", "content": "用 Python 写一个快速排序算法"}
    ]
)

print(response.output_text)

Node.js 示例:

typescript复制
import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

async function main() {
  const response = await openai.responses.create({
    model: 'gpt-5.2',
    input: [
      { role: 'system', content: '你是一个有帮助的助手。' },
      { role: 'user', content: '用 TypeScript 写一个快速排序算法' },
    ],
  });

  console.log(response.output_text);
}

main();

#核心 API

#Responses API（推荐）

统一入口，覆盖文本、多模态、工具调用与流式输出：

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

print(response.output_text)

#Chat Completions（兼容）

最常用的 API，用于对话和文本生成：

python复制
response = client.chat.completions.create(
    model="gpt-5.2",
    messages=[
        {"role": "system", "content": "系统提示"},
        {"role": "user", "content": "用户消息"},
        {"role": "assistant", "content": "助手回复"},
        {"role": "user", "content": "继续对话"}
    ],
    temperature=0.7,  # 创造性 0-2
    max_tokens=1000,  # 最大输出长度
    stream=True       # 流式输出
)

#Function Calling

让模型调用自定义函数：

python复制
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定城市的天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "城市名称"
                    }
                },
                "required": ["city"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="gpt-5.2",
    messages=[{"role": "user", "content": "北京今天天气怎么样？"}],
    tools=tools,
    tool_choice="auto"
)

#Embeddings

将文本转换为向量，用于语义搜索：

python复制
response = client.embeddings.create(
    model="text-embedding-3-small",
    input="这是一段需要向量化的文本"
)

embedding = response.data[0].embedding

#Vision (图像理解)

GPT-4 Vision 可以理解图像：

python复制
response = client.chat.completions.create(
    model="gpt-5.2",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "这张图片里有什么？"},
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/image.jpg"}
                }
            ]
        }
    ]
)

#最佳实践

#1. API Key 安全

python复制
# ❌ 错误：硬编码 API Key
client = OpenAI(api_key="sk-xxx...")

# ✅ 正确：使用环境变量
import os
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

#2. 错误处理

python复制
from openai import OpenAI, APIError, RateLimitError

try:
    response = client.chat.completions.create(...)
except RateLimitError:
    print("达到速率限制，请稍后重试")
except APIError as e:
    print(f"API 错误: {e}")

#3. 流式输出

对于长文本生成，使用流式输出提升用户体验：

python复制
stream = client.chat.completions.create(
    model="gpt-5.2",
    messages=[{"role": "user", "content": "写一篇长文章"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

#4. Token 计算

使用 tiktoken 预估 token 数量：

python复制
import tiktoken

encoding = tiktoken.encoding_for_model("gpt-5.2")
tokens = encoding.encode("Hello, world!")
print(f"Token 数量: {len(tokens)}")

#常见问题

#API 调用失败？

1. 检查 API Key 是否正确
2. 确认账户余额充足
3. 检查网络连接（可能需要代理）

#响应太慢？

1. 减少 max_tokens
2. 使用 gpt-5-mini 代替 gpt-5.2
3. 启用流式输出

#超出速率限制？

1. 实现重试机制
2. 使用指数退避
3. 升级账户 tier

一句轻松版总结：
API 接入就像开餐厅，模型是厨房，Prompt 是菜单，日志与重试是后厨流程。
菜好吃靠厨师，出餐稳定靠系统。

#下一步

• 快速开始 - 详细的入门教程
• Function Calling - 学习函数调用
• Embeddings - 构建语义搜索

---

提示：OpenAI 经常更新模型，关注 官方更新日志↗ 了解最新功能。