OpenAI Vision API 怎么用？

官方资料（2026-10-31 核对）：Images and vision · Responses API Reference · Image input cost calculator · Models

Vision、Images API 与文件输入先分清

本页只负责“输入图片、输出理解结果”。生成与编辑图片请看 OpenAI Images API 指南；文件生命周期和 purpose 请看 Files API 指南。把两类工作流拆开，才能分别追踪输入 Token、生成费用、准确率和失败原因。

最小可用示例：Responses API 分析一张图片

下面示例沿用官方当前 Vision 示例中的模型。生产环境应从当前 Models 页面选择支持图像输入且符合质量、延迟与成本要求的模型，不要把示例模型永久写死。

import OpenAI from "openai";

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

const response = await openai.responses.create({
  model: "gpt-6-astra",
  input: [{
    role: "user",
    content: [
      { type: "input_text", text: "列出图片里的主要物体，并说明不确定之处。" },
      {
        type: "input_image",
        image_url: "https://example.com/product.jpg",
        detail: "auto"
      }
    ]
  }]
});

console.log(response.output_text);

API Key 只能保存在服务端。若输出会进入订单、风控、审核或其他不可逆流程，应要求模型给出“不确定/无法判断”，并在业务层设置人工复核，而不是只依赖自然语言回答。

三种图片输入方式怎么选？

import fs from "node:fs";

// 先上传，再使用 file_id
const uploaded = await openai.files.create({
  file: fs.createReadStream("inspection.jpg"),
  purpose: "vision"
});

const result = await openai.responses.create({
  model: "gpt-6-astra",
  input: [{
    role: "user",
    content: [
      { type: "input_text", text: "读取标签文字；看不清的字段返回 null。" },
      { type: "input_image", file_id: uploaded.id, detail: "original" }
    ]
  }]
});

不要把 Base64、签名 URL 或用户图片写入普通请求日志。对外部 URL 设置允许协议、重定向次数、超时和内容类型校验；对上传文件验证真实格式、解码尺寸和资源消耗。

detail：auto、low、high、original 怎么选？

官方当前说明，detail 支持值取决于模型，省略时 Responses 与 Chat Completions 都默认 auto。对于 OCR、小物体和坐标任务，在模型支持时可评测 original；但 original 仍受像素和 patch 预算影响，也不会让模型自动变成精确 OCR 或检测器。

格式、载荷、数量与 patch 限制

• 支持格式：PNG、JPEG、WEBP 和非动画 GIF。
• 请求载荷：官方当前通用上限为每次请求总计 512 MB。
• 图片数量：每次请求最多 1,500 张图片。
• patch：patch-based 输入在选定模型和 detail 预处理后，每张图最多 30,000 个 patch；超出会拒绝，而不是自动缩到上限内。
• 上下文仍有限：图片 Token、文字提示和输出必须共同放入模型上下文，模型或 detail 的更低限制可能先触发。

图像 Token 与成本怎么估算？

Vision 图片会被转换为输入 Token；图片尺寸、detail、模型的 patch/tile 规则决定图像 Token，文字提示与模型输出另外计费。图片 Token 也会计入 TPM 限额。官方提供 Image input cost calculator，可按模型、尺寸与 detail 估算一张图片的标准输入成本。

• 记录模型、原始宽高、detail、图片数量、文字 Token、输出 Token 和实际 usage。
• 用“单位可用结果成本”评估：总费用 ÷ 通过人工或规则校验的结果数。
• 先裁剪无关边缘、修正旋转、放大小字区域，再决定是否使用 original。
• 不要把 GPT Image 生成/编辑价格套到 Vision 图片输入；两者是不同计费流程。

项目用量和预算告警见 API Usage 指南；当前模型价格应以官方 Models/Pricing 与成本计算器为准。

结构化抽取：让“无法判断”成为合法结果

产品目录、票据、包装或截图抽取最好使用 Structured Outputs，把字段、枚举、null 和置信说明写入 Schema。Schema 只能约束输出形状，不能保证图片事实正确；图片模糊、遮挡或文本太小时仍应返回空值并触发复核。

const response = await openai.responses.create({
  model: "gpt-6-astra",
  input: [{
    role: "user",
    content: [
      { type: "input_text", text: "提取商品名和批次号；看不清就返回 null。" },
      { type: "input_image", file_id: uploaded.id, detail: "original" }
    ]
  }],
  text: {
    format: {
      type: "json_schema",
      name: "label_fields",
      strict: true,
      schema: {
        type: "object",
        properties: {
          product_name: { type: ["string", "null"] },
          lot_number: { type: ["string", "null"] },
          uncertainty: { type: "string" }
        },
        required: ["product_name", "lot_number", "uncertainty"],
        additionalProperties: false
      }
    }
  }
});

更多 Schema 与 JSON mode 边界见 Structured Outputs 指南。

常见失败与排查顺序

Vision 的能力边界与安全

• 模型可能误读小字、旋转/倒置内容、非拉丁文字、图表线型、全景图和鱼眼图。
• 精确空间定位、棋盘位置、坐标和物体计数可能不可靠；计数往往只是近似。
• 不适合解读 CT 等专业医学影像，也不能用于医疗建议。
• 模型不读取原始文件名或元数据，且图片在分析前可能被缩放。
• 系统会阻止 CAPTCHA 提交；不要把 Vision 用于绕过访问控制或安全机制。
• 对人物照片、证件、未成年人、敏感场景和第三方图片建立最小化采集、访问控制、保留与删除策略。

如果输入或输出可能包含违规内容，可根据业务风险结合 Moderation API 和人工审核；高风险决策必须使用独立验证数据和适用的专业流程。

评测：按任务拆分而不是只看“看懂了吗”

固定图片集、问题模板、期望答案和评分规则；每次模型、detail、裁剪或提示词变化都用同一版本回归。日志只保存必要的请求 ID、模型、参数、耗时、usage 和脱敏标签，不保存敏感原图。

上线前检查清单

1. 已经区分 Vision 图片理解与 Images API 生成/编辑。
2. 模型当前支持图片输入；示例模型没有被当成永久默认。
3. URL、Base64 与 file_id 的选择、权限、保留和删除策略明确。
4. 格式、真实 MIME、解码尺寸、总载荷、图片数量和上下文限制都有前置校验。
5. auto/low/high/original 用真实样本比较过质量、延迟和成本。
6. OCR、计数、坐标、医学和其他高风险结果有专门工具或人工复核。
7. 多图已编号，输出允许 null/不确定，失败重试不会重复执行不可逆动作。
8. 图片 Token、文字 Token、输出、TPM 和单位可用结果成本都有监控。

常见问题

本文核对日期为 2026-10-31。模型、detail 行为、图片限制、Token 计算与价格会调整；生产上线前请重新读取官方 Images and vision、Models 与 Image input cost calculator。