开发者文档 图片理解
图片理解
在同一条消息中发送问题与图片内容块。
使用前确认
需要:支持图片输入的 Chat Completions 模型;图片地址能被上游访问。控制台的「图片理解」标记,或 /v1/models 返回的 capabilities.image_input.supported,表示模型接受图片;网关不检查,图片内容块原样交给上游。先完成快速开始中的环境变量配置,并把 YOUR_MODEL_ID 换成这把密钥可用的模型 ID。
完整示例
可从页头“下载代码”保存为 .py 文件,在配置好环境的服务端运行。
import os, json, urllib.request, urllib.error
BASE = os.environ["MOSSHUB_API_BASE"].rstrip("/")
KEY = os.environ["MOSSHUB_API_KEY"]
MODEL = "YOUR_MODEL_ID"
def chat(messages, **options):
body = {"model": MODEL, "messages": messages, "stream": False, **options}
request = urllib.request.Request(
BASE + "/v1/chat/completions",
data=json.dumps(body, ensure_ascii=False).encode("utf-8"),
headers={"Authorization": "Bearer " + KEY,
"Content-Type": "application/json"}, method="POST")
try:
with urllib.request.urlopen(request, timeout=60) as response:
result = json.load(response)
except urllib.error.HTTPError as error:
raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8')}") from error
choices = result.get("choices", [])
if not choices or not isinstance(choices[0].get("message"), dict):
raise RuntimeError("未返回有效消息,请检查错误信息与模型能力")
if choices[0].get("finish_reason") == "length":
raise RuntimeError("回答因输出上限而截断,请调整预算后重试")
return choices[0]["message"]
image_url = os.environ["MOSSHUB_IMAGE_URL"]
if not image_url.startswith("https://"):
raise ValueError("请提供可公开访问的 HTTPS 图片地址")
message = chat([{"role": "user", "content": [
{"type": "text", "text": "描述这张图片的主要内容,并列出三个可见细节。"},
{"type": "image_url", "image_url": {"url": image_url}},
]}])
content = message.get("content")
if not isinstance(content, str):
raise RuntimeError("当前返回不是文本,请检查消息与模型能力")
print(content)先准备图片地址
除 API 地址和密钥外,设置 MOSSHUB_IMAGE_URL 为上游能直接下载的公开 HTTPS 图片地址。网关只转交地址,不下载也不保存图片;临时链接需要在请求处理期间保持有效。
示例只接受 HTTPS 地址,不上传本地文件。本地图片可改写成 base64 的 data: 地址放进 url,是否接受由上游决定,图片数据计入请求体大小。
输入与生成的区别
本例是理解已有图片,输出文本。图像生成说明的是另一类接口。
出错时
模型不支持图片、图片无法下载或格式不被接受时,网关不会提前拦截,而是原样返回上游的状态码和错误正文。链接无法访问时,先检查有效期、鉴权要求和资源类型。
图片格式、大小和数量上限由上游决定;网关只限制整个请求体不超过 32 MiB,超出返回 413 request_too_large。
继续阅读
实际可调用的模型、授权与价格以控制台为准。
页面字体:MiSans(小米,依《MiSans 字体知识产权许可协议》使用);Google Sans Flex(SIL Open Font License 1.1)。
页面字体:MiSans(小米,依《MiSans 字体知识产权许可协议》使用);Google Sans Flex(SIL Open Font License 1.1)。