API 怎么传图片？图片 URL、Base64 与识图验收

云岚API · 教程 · 更新于 2026-10-25

API 传图片，要先选支持图像输入的模型和端点，再把图片放进该协议的图像内容块。走本文的 Base64 方式时，本地文件需要读取并编码；线上图片需要可取到文件的地址；把文件路径或网页链接写进普通文字，不等于提交了图片。本文分别说明三种请求结构，并提供验收模板；示例没有调用真实 API，也没有上传图片。官方资料核对日期为 2026 年 10 月 24 日。

先分清图片直链、网页地址和 Base64

手里有什么	应怎样准备	容易混淆的地方
在线图片文件地址	按接口要求放入图片字段	图片所在文章、网盘预览页可能返回 HTML
本地 PNG 或 JPEG 截图	读取文件字节，再做 Base64 编码	`C:\\截图.png` 或 `./shot.png` 只对自己的程序有意义
一串 Base64 字符	按协议决定是否加 data URL 前缀	原始编码与完整 data URL 不是同一种字段值

data URL 的形状是 data:image/png;base64,编码内容。其中 MIME 描述图片类型，逗号后才是编码；给 JPEG 改一个 .png 后缀并不会转换文件。先确认真实格式，再填写对应 MIME。

先用一张清晰、小尺寸、自己有权使用的非敏感截图完成流程。多图、长截图、文件上传后引用 ID，可以在单图验收通过后增加；文件大小和数量限制须查所选接口，不沿用其他平台的上限。

OpenAI 两个接口，图片字段怎样写？

先在记录表填好服务地址、端点、模型标识和 SDK 版本，确认文档写的是这个组合支持图像输入。如果原先文本请求可用而加图后失败，保留同一组合，先查图片来源和内容块；不要同时更换模型、协议与图片格式，否则即使下一次成功，也难以知道修好了哪一步。框架可能自动改写消息，排查时还应查看脱敏后的实际请求结构，不能只看界面上是否出现缩略图。

以下都是请求体片段，省略了模型、鉴权及其他参数，YOUR_IMAGE_URL_OR_DATA_URL 需要替换，不能直接发送。它可以是图片直链，也可以是编码后的 data URL。这里的结构依据 OpenAI 官方指南，不代表云岚API每个模型和渠道都支持这些入口。OpenAI 图片输入指南

Chat Completions 的 /v1/chat/completions 用 messages，图片块中 image_url 是含 url 的对象：

{
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "读出截图标题和按钮文字；看不清就标明。"},
      {"type": "image_url", "image_url": {"url": "YOUR_IMAGE_URL_OR_DATA_URL"}}
    ]
  }]
}

Responses 的 /v1/responses 用 input，图片类型为 input_image，其 image_url 直接接收字符串。不要只改端点却保留前一种消息结构。

{
  "input": [{
    "role": "user",
    "content": [
      {"type": "input_text", "text": "读出截图标题和按钮文字；看不清就标明。"},
      {"type": "input_image", "image_url": "YOUR_IMAGE_URL_OR_DATA_URL"}
    ]
  }]
}

如果图片在本地，下面仅用 Python 标准库生成 PNG 的 data URL，不联网、不发请求；先将路径替换为真实 PNG 文件。变量包含完整图像数据，无需打印到日志。

from pathlib import Path
import base64

raw = Path("your-screenshot.png").read_bytes()
encoded = base64.b64encode(raw).decode("ascii")
image_data_url = "data:image/png;base64," + encoded

把 image_data_url 的值放进对应图片字段。若是 JPEG，先确认文件格式并将 MIME 改为 image/jpeg。地址拼接仍有疑问，可对照 base_url 与端点说明；图片内容块是否正确，需要另行检查。

Anthropic Messages 不能直接照搬 image_url

Anthropic Messages 使用 image 块和 source。Base64 方式将 MIME 单独放在 media_type，data 只放原始编码，不能把 OpenAI 示例中的完整 data URL 原样塞进去。以下仍是待填的请求片段。Anthropic 视觉输入文档

{
  "messages": [{
    "role": "user",
    "content": [
      {"type": "image", "source": {
        "type": "base64",
        "media_type": "image/png",
        "data": "YOUR_RAW_BASE64"
      }},
      {"type": "text", "text": "读出截图标题和按钮文字；看不清就标明。"}
    ]
  }]
}

若使用图片 URL，source 改为 {"type":"url","url":"YOUR_IMAGE_URL"}。同一个模型名称出现在不同服务上，也应按实际端点查格式；“OpenAI 兼容”不能替代对图像输入能力的确认。

浏览器能打开，为什么 API 仍然取不到图？

需要取图的是服务端，浏览器里已有的登录状态不代表服务端也具备。腾讯云的图片理解文档明确要求其 URL 方式能够公网直接访问，并为私有存储提供预签名 URL 或 Base64 两种思路；具体服务仍应遵循自己的规则。图片 URL 传入条件

按顺序检查：

地址最终返回图片文件，还是登录页、预览页或防盗链提示？仅看 URL 以 .jpg 结尾不够。
图片是否依赖 Cookie、内网地址或过期签名？临时链接的有效期要覆盖服务端取图时点，不能据此推定具体抓取延迟。
错误指向图片下载、编码解析，还是消息字段类型？先保存脱敏错误和请求标识，再只改变一个条件复查。

无登录环境能获取图片，只是排查线索，不能保证供应商服务器也能访问。如果使用敏感截图，先脱敏并确认数据处理要求；Base64 是编码，不是加密，随请求发送后服务仍会接收到图像内容。

怎样验收这次请求真的完成了图片任务？

先人工查看原图，私下写好三项答案，例如标题文字、某个数值及其标签、一个按钮相对标题的位置。提示词只提出任务，不把答案放进问题或文件名。要求看不清时明确说明，再逐项比对输出；不能仅凭“这是一张网页截图”之类泛泛描述判定通过。

验收层次	留下什么证据
请求结构	协议、模型、图片块位置、输入方式、实际 MIME 和尺寸
接口处理	请求标识、HTTP 状态、结束状态、完整正文或脱敏错误
图片任务	预先标注的答案、实际回答、正确项、遗漏和无法判断项
费用与复查	原始 usage、账单单位、耗时、重试次数及本次只改了什么

小字、旋转和复杂空间关系会影响识别；可以保留原图，再用裁剪或放大后的版本做单独对照，记录变化，不把其中一次答对当作所有图片都可靠。OpenAI 图像理解限制

下载图片输入检查与验收模板。包内包含请求检查清单、人工答案表及空白 CSV，不含图片、密钥或实测成绩。记录只证明这个样本在当时配置下的表现，不能认证模型身份。若需要把截图信息输出为固定字段，继续看 JSON 与结构化输出验收。

常见问题

HTTP 200，就能认定识图成功吗？

不能。还要检查响应是否完整、有无拒绝或错误信息，再按原图核对任务结果；没有完成文字提取或位置判断，就不能记为该任务通过。

Base64 比图片 URL 更省钱吗？

不能仅按传输方式判断。OpenAI 将图像输入计入用量，具体计算还涉及模型、尺寸和细节设置；不要把 Base64 字符数直接当作图像 token 数。实际费用应保留 usage 并与账单口径核对。官方图像计费说明

把链接写在“请看这张图”后面可以吗？

本文所述直接图像输入需要专用内容块。普通文本中的链接不能替代它；其他工具是否会抓取网页，属于另一条流程。

在云岚API怎么开始验证？

已有账号先到控制台核对目标模型和端点，确认图像输入方式后再用一张非敏感图验收；尚未接入可先读API 接入教程。本文不承诺全部模型、渠道或客户端都兼容上述格式。

输入整份 PDF 时，继续检查文件和页码

单张图片的内容块不能代表全部文件协议。处理整份文档时，先确认接口接受哪种 PDF 文件输入，再核对扫描页、文本和引用位置。参见 PDF 文件输入与页码证据验收；不要仅凭模型说“已阅读文件”判断全文都已处理。

生成图片以后，怎样保存成可用文件？

本文处理给模型传图。若任务是接收生成的图片，继续看图片生成结果的解码、下载与文件验收，分别核对图片字段、实际格式、最终产物和逐图记录，不能把能识图当作支持生图的证明。