Hugging Face Responses API 怎么同时发送文本和图片输入

想让 Hugging Face Responses API 同时理解一段说明和一张图片，关键不是把图片地址拼到文本里，而是把两者放进同一个 user 消息的 content 数组：文字使用 input_text，图片使用 input_image，图片地址放在 image_url。客户端再把 base_url 指向 Hugging Face Router，并使用有 Inference Providers 权限的 HF_TOKEN。

最小可行结构是“一个 Responses API 请求 + 一个 content 数组 + 两个内容部件”。文本负责提出任务，图片负责提供视觉上下文；如果返回 401/403，先查令牌权限，如果返回 400，再查 content 结构、模型能力和图片 URL。

先把多模态请求边界拆开

Responses API 的输入模型与只传一段字符串不同。调用方仍然使用 OpenAI SDK 的客户端，但目标地址改成 Hugging Face 的兼容路由；真正的多模态部分位于 input 数组内。数组元素声明角色为 user，其 content 再列出文本和图片。

下面的示例故意把图片地址写成占位地址。实际使用时，应替换为推理服务端能够通过 HTTPS 访问的图片 URL；不要把本地路径如 /Users/me/photo.jpg 直接填进 image_url。

用一个 content 数组发送文本和图片

安装 openai 后，可以先用最小请求确认结构是否正确。代码中的中文注释只解释关键边界，不把令牌写入源码：

import os
from openai import OpenAI

client = OpenAI(
    # Hugging Face 的 OpenAI 兼容路由
    base_url="https://router.huggingface.co/v1",
    # 令牌从环境变量读取，避免进入代码仓库
    api_key=os.environ["HF_TOKEN"],
)

response = client.responses.create(
    # 选择支持视觉输入的模型，具体可用模型以当前路由为准
    model="Qwen/Qwen2.5-VL-7B-Instruct",
    input=[
        {
            "role": "user",
            "content": [
                # 文本提出要模型回答的任务
                {"type": "input_text", "text": "请描述图片中的主要对象，并指出一个可观察的细节。"},
                {
                    # 图片必须通过推理服务可访问的 URL 提供
                    "type": "input_image",
                    "image_url": "https://cdn.example.com/demo/scene.jpg",
                },
            ],
        }
    ],
)

# output_text 是读取文本答案的便捷字段
print(response.output_text)

这段代码有四个容易混淆的点：base_url 决定请求发往 Hugging Face；model 决定推理模型；content 是内容部件列表；image_url 只是图片资源地址，不是图片二进制本身。官方示例也采用这种把文本和视觉内容混在一个 input 数组中的形式。

为什么 400、401 和图片读取失败不是同一个问题

多模态调用失败时，先看错误落在哪一层。401 或 403 通常指向令牌无效、权限不足或账户没有可用的 Inference Providers 访问能力；这时改 content 结构没有意义。400 更常见于字段层级、内容类型拼写、模型不接受视觉输入，或者请求体不符合当前接口约定。

请求已经被接受但模型无法理解图片时，优先检查图片 URL：是否为完整的 HTTPS 地址、是否需要登录、是否会跳转到不可访问的页面、响应是否真的是图片，以及外部服务是否限制了抓取。浏览器能打开并不等于推理服务所在网络一定能读取。

把鉴权、模型与图片可达性列入排查清单

安全上，图片是外部输入，令牌是访问凭据，模型与 provider 是路由依赖，四者不应混成一个“接口不稳定”的结论。生产调用至少记录请求时间、模型标识、provider（如果显式指定）和错误类型；不要记录 HF_TOKEN，也不要把含个人信息的原图复制进日志。

如果需要固定 provider，官方文档允许把 provider 后缀附在模型 ID 后；不固定时由路由按默认策略选择可用 provider。这个选择可能影响延迟、费用和模型可用性，所以先用不带私有参数的最小请求跑通，再根据业务需要收紧路由。图片方面则优先使用短时效、最小权限的资源代理，避免把永久公开的敏感图片地址直接交给第三方推理服务。

相关问题

能不能把图片放进普通字符串里？

不建议。普通字符串只表达文本；视觉输入应使用 input_image 内容部件，并把可访问地址放进 image_url。

本地图片路径可以直接传吗？

不可以。服务端无法读取调用机器的本地路径。应先放到合适的图片服务，或使用当前接口明确支持的可传输形式，并保证请求格式符合官方文档。

为什么同样的代码换模型后失败？

Responses API 的请求形状可以保持不变，但模型是否支持视觉输入、provider 是否提供该模型以及账户是否有额度，都会变化。先查模型能力和当前 provider 状态，再判断代码是否需要修改。

小结：同时发送文本和图片的核心是同一个 content 数组里的两种部件，而不是拼接字符串。先固定客户端与输入契约，再分层检查令牌、模型路由、图片可达性和输出字段，排错会快很多。参考：Hugging Face Responses API 官方文档。