OpenAI API 怎样把图片输入和文本问题放在同一请求

需要让模型根据一张图片回答问题时，关键不是把图片地址拼到文字里，而是在同一个 input 消息的 content 数组中放入两个内容项：一个是 input_text，另一个是 input_image。Responses API 会把它们当作同一次用户输入处理。

官方地址：https://developers.openai.com/api/docs/guides/images-vision

同一个 input 消息里同时放文本和图片

官方 Responses API 示例使用 input_text 表达问题，使用 input_image 表达图片。下面的最小 Python 代码采用公开图片 URL，适合先验证请求结构；模型名请替换为当前项目可用的视觉模型。

import os
from openai import OpenAI

# 客户端从环境变量读取密钥，不把密钥写进源码或日志。
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

response = client.responses.create(
    model="gpt-6-astra",
    input=[
        {
            "role": "user",
            "content": [
                # 文字是对图片提出的具体任务。
                {"type": "input_text", "text": "请描述图片中的主体，并指出最明显的颜色。"},
                {
                    "type": "input_image",
                    # URL 必须是完整地址，并且服务端能够访问。
                    "image_url": "https://openai-documentation.vercel.app/images/cat_and_otter.png",
                    # 先用 auto；只有细节不足时再提高 detail。
                    "detail": "auto",
                },
            ],
        }
    ],
)

# Responses API 将模型的文本结果聚合在 output_text 中。
print(response.output_text)

这里的顺序也有可读性价值：先写任务，再给图片，读者能直接看出模型要对哪张图片完成什么动作。一次请求也可以放多张图片，但图片会占用输入 token，应只提交回答确实需要的图片。

URL 与 Base64 的选择边界

如果图片已经放在可访问的对象存储或公开地址，使用 URL 最简单。本地文件不能直接把 macOS 或服务器路径交给 API，需要读取二进制内容并拼成 data URL。MIME 类型必须与实际文件一致，例如 PNG 使用 image/png，JPEG 使用 image/jpeg。

import base64
from pathlib import Path
from openai import OpenAI

# 将本地图片转换为 data URL，避免把本机路径当成远程地址发送。
def to_data_url(path: str) -> str:
    file_path = Path(path)
    encoded = base64.b64encode(file_path.read_bytes()).decode("ascii")
    # 示例固定处理 PNG；若文件是 JPEG/WEBP，应同步修改 MIME。
    return f"data:image/png;base64,{encoded}"

client = OpenAI()
image_data_url = to_data_url("examples/diagram.png")

response = client.responses.create(
    model="gpt-6-astra",
    input=[{
        "role": "user",
        "content": [
            # 问题和图片仍然属于同一个 user 消息。
            {"type": "input_text", "text": "请找出图中三个主要模块，并按从左到右列出。"},
            {"type": "input_image", "image_url": image_data_url, "detail": "auto"},
        ],
    }],
)

print(response.output_text)

运行后怎样判断请求真的成功

先确认 SDK 请求没有抛出异常，再看 response.output_text 是否围绕图片回答了问题。回答为空时不要先反复改提示词，按下面顺序检查：

1. 图片 URL 是否完整，是否要求登录、临时签名或来源校验；本地文件则确认 Base64 前缀与 MIME 类型匹配。
2. 请求结构是否为 input → role:user → content[]，并且图片项类型写成 input_image。
3. 模型是否支持图片输入；模型名、SDK 版本和项目权限应以当前官方文档及账号可用模型为准。
4. 问题是否具体，例如“列出三个模块”比“看看这张图”更容易得到可核对的结果。

detail 解决的是图片细节级别，不会修复失效 URL，也不会把普通文本模型变成视觉模型。先用 auto 建立可用基线，再针对小字、局部结构等确实需要的场景调整。

常见问题

能不能把图片地址直接接在问题字符串后面？

不建议。那只是普通文本，模型未必会把它当作图片输入。应在 content 中单独放 input_image。

本地图片为什么不能写成 /tmp/a.png？

这是本机路径，不是 API 可访问的图片地址。需要改成可访问 URL，或编码成带 MIME 的 Base64 data URL。

一次请求可以放多张图片吗？

可以，把多个 input_image 放进同一数组，并在文字中说明比较顺序；图片数量越多，输入成本和上下文负担也越高。

如何避免把密钥或私人图片泄露到代码里？

密钥只从环境变量读取，私有图片优先评估访问范围、有效期和数据合规要求；不要把密钥、内部路径或敏感图片写入日志和示例仓库。