OpenAI 的 O3 API：逐步教程与示例

OpenAI 的 o3 模型能够解决复杂的多步问题，融合视觉与文本输入，并使用 Python、搜索或图像检查等工具来提升答案质量。

在本教程中，我将逐步讲解如何通过 API 使用 o3、o3 与 GPT-4o 等通用模型的不同之处，以及如何有效管理推理成本。

我们通过免费周报 The Median 为读者带来 AI 前沿动态，每周五精炼解读一周要闻。订阅即可用几分钟保持敏锐：

何时应该使用 O3？

OpenAI 的 o3 模型面向需要深度推理与高度自主性的高级复杂任务。在软件开发、数学、科学研究以及视觉数据解读等领域的复杂问题求解方面尤为有效。

该模型的“智能体式”能力使其能够自主调用网页搜索、Python、图像生成等工具，适用于需要多步分析与动态决策的任务。

当您的项目涉及复杂的多模态推理任务，并可受益于其高自主性与高级分析能力时，应考虑通过 API 使用 o3 模型。

下面快速比较一下 o3、o4-mini 与 GPT-4o：

来源：OpenAI

使用 API 时，定价同样是需要考虑的重要因素：

来源：OpenAI

OpenAI O3 API：如何连接到 OpenAI 的 API

在开始使用 o3 的高级推理能力之前，您需要先配置对 OpenAI API 的访问。在本节中，我将带您完成：

• 安全设置您的 API 密钥
• 向 o3 模型发出您的第一个 API 调用
• 突出推理模型在设置上的关键差异

步骤 1：获取 API 凭证

要访问 OpenAI API，您需要一个有效的 API 密钥，您可以在 OpenAI API Keys 页面获取，并确保已启用计费功能。

注意：要使用 o3，您必须先在 此处验证您的 OpenAI 组织。验证可能需要最多 15 分钟生效。

步骤 2：导入 openai 库

我们先安装并升级 openai 库，以便通过 API 访问 O3 模型。运行以下命令：

pip install --upgrade openai技术支持

安装完成后，从 openai 库中导入 OpenAI 类：

from openai import OpenAI技术支持

步骤 3：初始化客户端对象

要与 OpenAI 的 API 交互，我们通过设置密钥 API 来进行身份验证，从而可以向 o3 等模型发起授权请求。

client = OpenAI(api_key=YOUR_API_KEY)技术支持

步骤 4：发起一次 API 调用

完成设置后，我们通过 Responses API 向 o3 发起第一次调用，看看它如何处理一个简单的多步推理任务。

示例 1：无需工具的简单提示

先用一个简单的提示了解 o3 的 API 调用。

response = client.responses.create(
    model="o3",
    input=[{"role": "user", "content": "What’s the difference between inductive and deductive reasoning?"}]
)
print(response.output_text)技术支持

此示例将自然语言问题直接发送给 o3 模型，不使用任何工具或特殊推理参数。

• model="o3" 指示 API 使用 o3 推理模型。
• input=[{"role": "user", "content": "..."}] 定义了一条用户消息，请求概念性解释。
• O3 在生成最终输出前，内部默认采用中等力度的推理链。

以下这些 token 将计入最终成本：

• 输入 token：提示词
• 推理 token：o3 的内部思维链（chain-of-thought） 
• 输出 token：最终输出

示例 2：代码与数学问题求解

在此示例中，我们要求 o3 同时编写代码并解释解二次方程背后的数学原理。这是一个分两部分的任务，既需要编码，也需要详细的数学说明。

prompt = "Write a Python function that solves quadratic equations and also explain the math behind it."
response = client.responses.create(
    model="o3",
    reasoning={"effort": "high"},
    input=[{"role": "user", "content": prompt}]
)
print(response.output_text)技术支持

该任务需要多步数学推理，先求解二次公式，再解释其推导过程。参数 reasoning={"effort": "high"} 会让 o3 “更费脑”，生成更长的推理轨迹。非常适合需要技术深度或多阶段解法的任务。

成本提示：更高的推理力度意味着更多推理 token，从而带来更高的输出成本。

示例 3：代码重构任务

在此示例中，我们向 O3 提交一个代码重构任务，并附上多条说明。

prompt = """
Instructions:
- Given the React component below, change it so that nonfiction books have red
  text. 
- Return only the code in your reply
- Do not include any additional formatting, such as markdown code blocks
- For formatting, use four space tabs, and do not allow any lines of code to 
  exceed 80 columns
const books = [
  { title: 'Dune', category: 'fiction', id: 1 },
  { title: 'Frankenstein', category: 'fiction', id: 2 },
  { title: 'Moneyball', category: 'nonfiction', id: 3 },
];
export default function BookList() {
  const listItems = books.map(book =>
    <li>
      {book.title}
    </li>
  );
  return (
    <ul>{listItems}</ul>
  );
}
"""
response = client.responses.create(
    model="o3",
    reasoning={"effort": "medium", "summary": "detailed"},
    input=[
        {
            "role": "user",
            "content": prompt,
        }
    ]
)
print(response.output_text)技术支持

在上述代码中，我们为 O3 提供了一个结构化的代码编辑任务，并附有详细的格式化规则。

• reasoning={"effort": "medium"} 参数指示其在谨慎推理的同时保持高效。
• summary="detailed" 参数请求对模型思考过程的完整内部摘要。O3 将进行内部推理，如果您稍后查看 summary 字段，可选择性返回总结过的轨迹。

提示：可用的摘要设置包括 "concise"、"detailed" 或 "auto" 等。

示例 4：视觉推理

让我们使用这张大会照片，并让 o3 基于我们的兴趣生成日程安排。

步骤 4.1：辅助函数

先导入所需库并编写一个辅助函数：

import base64, mimetypes, pathlib
def to_data_url(path: str) -> str:
    mime = mimetypes.guess_type(path)[0] or "application/octet-stream"
    data = pathlib.Path(path).read_bytes()
    b64  = base64.b64encode(data).decode()
    return f"data:{mime};base64,{b64}"技术支持

函数 to_data_url() 将本地图像文件转换为 base64 编码的数据 URL，因为 OpenAI 的 API 期望以 URL 格式接收图像输入，而非原始文件。

to_data_url 函数的流程如下：

• 从您的电脑读取图像文件（路径）。
• 推断其类型（例如 image/png）。
• 将二进制内容编码为 base64 字符串。
• 最终返回数据 URL。

步骤 4.2：同时向 O3 发送文本与图像

对图像完成编码后，我们将文本与编码后的图像信息一并传递给 O3。

prompt = (
    "Create a schedule using this blurry conference photo. "
    "Ensure 10-minute gaps between talks and include all talks related to LLMs."
)
image_path   = "IMAGE_PATH"
image_url    = to_data_url(image_path)        
response = client.chat.completions.create(
    model="o3",                                  
    messages=[
        {
            "role": "user",
            "content": [
                { "type": "text",      "text": prompt },
                { "type": "image_url", "image_url": { "url": image_url } }
            ],
        }
    ],
)
print(response.choices[0].message.content)技术支持

其工作方式如下：

• 我们调用 client.chat.completions.create()，输入内容是一个列表，包含：
• 文本指令（用户的排期请求），
• 以及图像数据（大会照片）。
• o3 模型会在其内部思维链中联合处理这两种输入。
• 最后，我们打印 response.choices[0].message.content，其中包含模型在综合文本指令与视觉数据后生成的日程。

重要的成本考量：

• 图像输入按输入 token 计费。
• 模型会在推理循环中进行视觉检查。
• 如果推理链较长，应使用 max_completion_tokens 参数谨慎管理成本，我们将在下一节介绍。

来看下结果：

用推理 token 管理成本

O3 除常规输入/输出 token 外，还会使用推理 token，这意味着总 token 数更多，从而输出成本更高。延续上个示例，我们来拆解推理 token 如何影响成本。

print(response.usage)技术支持

CompletionUsage(completion_tokens=3029,prompt_tokens=1007, total_tokens=4036, completion_tokens_details=CompletionTokensDetails(accepted_prediction_tokens=0, audio_tokens=0, reasoning_tokens=2112, rejected_prediction_tokens=0), prompt_tokens_details=PromptTokensDetails(audio_tokens=0, cached_tokens=0))技术支持

如果您想控制成本，可使用 max_completion_tokens 参数为总用量设定上限：

limit_token_response = client.chat.completions.create(
    model="o3",                                  
    messages=[
        {
            "role": "user",
            "content": [
                { "type": "text",      "text": prompt },
                { "type": "image_url", "image_url": { "url": image_url } }
            ],
        }
    ],
    max_completion_tokens=3000,
)
print(limit_token_response.usage)技术支持

CompletionUsage(completion_tokens=2746, prompt_tokens=1007, total_tokens=3753, completion_tokens_details=CompletionTokensDetails(accepted_prediction_tokens=0, audio_tokens=0, reasoning_tokens=2112, rejected_prediction_tokens=0), prompt_tokens_details=PromptTokensDetails(audio_tokens=0, cached_tokens=0))技术支持

从上述输出可见，设置 max_completion_tokens 对控制模型行为至关重要。通过限定最大生成 token 数，可避免 o3 产生不必要的长输出或消耗过多推理 token，从而优化总体 API 成本。对于内部推理可能占据大量 token、但未必相应增加用户可见输出的复杂任务，这一点尤其重要。

重要：在使用 o3 处理复杂视觉任务时，请将 max_completion_tokens 设置为保守但偏高的值。若上限过低，模型可能在内部推理阶段耗尽 token 而无法返回可见输出。

O3 的提示词最佳实践

与GPT-4o 或 Claude 3.5 Sonnet 等通用模型不同，O3 在内部进行深入的思维链推理。它在直截了当、目标导向的提示下表现最佳，即过度指定步骤可能会降低效果。

以下是 OpenAI 建议的 o3 提示词最佳实践：

• 保持提示简洁清晰： O3 擅长处理直接指令，无需冗长解释。
• 避免“思维链”提示： 无需要求 O3 “逐步思考”——它会在内部完成推理。
• 使用分隔符以提高清晰度： 可用三引号、XML 标签或其他分隔符组织输入的不同部分。
• 限制额外上下文： 若使用检索增强生成（RAG），仅包含最相关的信息，避免给模型造成负担。

结语

在本文中，我们学习了如何通过 API 连接到 OpenAI 的 O3 模型、如何管理推理 token 成本，以及如何依据最佳实践编写高效提示词。若您的项目需要高级推理能力，如多步数学推理、代码重构或视觉理解，O3 是优选方案。

若要进一步了解 API 的使用，推荐阅读以下博客：

• O4-Mini API：逐步教程含演示项目
• Grok 3 API：逐步指南与示例
• GPT-Image-1 API：逐步指南与示例
• DeepSeek API：示例与成本计算指南