API选
入门教程

OpenAI 兼容 API 图片输入教程：Base64、图片 URL 与模型能力验证（2026）

用统一的 OpenAI 兼容格式发送图片，讲清图片 URL、Base64、MIME 类型、文件大小限制和模型能力验证，附 curl、Python、Node.js 示例。

发布：2026年8月28日

很多服务商宣称“兼容 OpenAI API”，但文本请求成功，不代表图片输入也可用。图片请求同时涉及消息格式、模型能力、文件大小和图片来源权限，最好单独做一次最小测试。

一、先确认三个条件

  1. 服务商的 Base URL 确实提供 /v1/chat/completions 或文档中指定的兼容路径；
  2. 当前模型支持视觉输入，而不是只支持文本；
  3. 服务商允许使用远程图片 URL，或者允许传递 data URL。

不要直接把普通的 content: "请描述这张图" 和图片路径混在一起。多模态消息通常需要数组格式：

{
  "role": "user",
  "content": [
    {"type": "text", "text": "请用一句话描述图片"},
    {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
  ]
}

二、用图片 URL 做第一次测试

图片 URL 必须能被服务商服务器访问，不能依赖你的本地电脑、内网地址或需要登录的网盘。使用 curl 时可以这样发送：

curl https://你的服务商地址/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"支持视觉的模型","messages":[{"role":"user","content":[{"type":"text","text":"图片里有什么？"},{"type":"image_url","image_url":{"url":"https://example.com/photo.jpg"}}]}],"max_tokens":200}'

如果返回 400，先检查 JSON 结构和 model id；如果返回下载失败，通常是 URL 不公开、证书异常、返回了 HTML，或者图片太大。

三、本地图片转 Base64

当图片不能公开访问时，可以转换为 data URL。注意 Base64 会让请求体变大，生产环境要设置大小上限。

import base64
import mimetypes
from pathlib import Path

path = Path('photo.jpg')
mime = mimetypes.guess_type(path.name)[0] or 'image/jpeg'
encoded = base64.b64encode(path.read_bytes()).decode('ascii')
image_url = f'data:{mime};base64,{encoded}'
body = {
    'model': '支持视觉的模型',
    'messages': [{'role': 'user', 'content': [
        {'type': 'text', 'text': '请描述这张图片'},
        {'type': 'image_url', 'image_url': {'url': image_url}},
    ]}],
}

常见 MIME 类型是 image/jpeg、image/png 和 image/webp。不要只根据文件扩展名猜测，上传前最好读取文件头并拒绝不支持的格式。

四、Node.js 的最小请求

import { readFile } from 'node:fs/promises'

const bytes = await readFile('./photo.jpg')
const base64 = Buffer.from(bytes).toString('base64')
const response = await fetch(`${baseUrl}/v1/chat/completions`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: '支持视觉的模型',
    messages: [{ role: 'user', content: [
      { type: 'text', text: '请描述图片中的主要对象' },
      { type: 'image_url', image_url: { url: `data:image/jpeg;base64,${base64}` } },
    ]}],
  }),
})
console.log(await response.json())

五、为什么文本模型会返回“参数错误”

兼容协议只代表请求外形相近，不代表所有模型都实现视觉能力。用同一个 Base URL 逐项测试：文本模型、视觉模型、小尺寸图片、较大图片。把每次测试的 model id、HTTP 状态码和响应耗时记录下来，才能区分“模型不支持”和“服务商没有转发图片”。

六、安全和成本注意事项

  • 图片可能包含身份证、合同或聊天截图，发送前先打码；
  • Base64 会增加请求体体积，可能触发网关 413；
  • 图片通常会计入输入 Token，不能只看文本价格；
  • 不要把带签名、带用户隐私的图片 URL 写入日志；
  • 失败重试前检查服务商是否已经成功接收图片，避免重复扣费。

推荐顺序是：公开小图片 URL → 本地小图片 Base64 → 生产环境加入尺寸、格式、超时和隐私检查。

标签：多模态图片输入OpenAI兼容Base64API配置
返回教程列表