大模型服务平台 TokenHub 图片理解

一、支持的模型

TokenHub 提供多款支持图片理解能力的模型，涵盖专用多模态模型与具备多模态能力的语言模型。完整模型列表及能力说明，请参见 模型列表。

二、支持的 API

三、图片传入方式（URL / Base64）

图片支持通过 URL 或 Base64 两种方式传入。在 Chat Completions 协议中，图片数据填入 image_url 的 url 字段；在 Responses 协议中，图片数据填入 input_image 的 image_url 字段。两种方式的核心差异如下：

四、方式一：图片 URL 传入

适用于图片已存储在公网可访问位置的场景。

请求结构（Chat Completions 协议）：

{ "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" }}

请求结构（Responses 协议）：

{ "type": "input_image", "image_url": "https://example.com/photo.jpg"}

请求结构（Anthropic 协议）：

{ "type": "image", "source": { "type": "url", "url": "https://example.com/photo.jpg" }}

五、方式二：图片 Base64 传入

适用于图片无法公网访问的场景。将图片读取为二进制后做 Base64 编码，并以 data:<mime>;base64,<编码> 的形式填入 image_url.url。常见图片 MIME：image/jpeg、image/png、image/webp。

请求结构（Chat Completions 协议）：

{ "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,<BASE64_DATA>" }}

请求结构（Responses 协议）：

{ "type": "input_image", "image_url": "data:image/jpeg;base64,<BASE64_DATA>"}

请求结构（Anthropic 协议）：

{ "type": "image", "source": { "type": "base64", "media_type": "image/jpeg", "data": "<BASE64_DATA>" }}

六、调用示例

下面示例均使用 OpenAI Chat Completions 协议（POST /v1/chat/completions），以 hy4 模型为例。图片通过 content 中的 image_url 类型块传入，支持单图与多图两种输入。

七、单图输入

cURL（单图 URL）Python（单图 URL）Python（单图 Base64）curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \\ -H 'Authorization: Bearer YOUR_API_KEY' \\ -H 'Content-Type: application/json' \\ -d '{ "model": "hy4", "messages": [{"role": "user", "content": [ {"type": "image_url", "image_url": {"url": "YOUR_IMAGE_URL"}}, {"type": "text", "text": "请描述这张图片的内容，并说出图中有几只动物。"} ]}], "stream": false }'from openai import OpenAIclient = OpenAI( api_key="YOUR_API_KEY", base_url="https://tokenhub.tencentmaas.com/v1",)response = client.chat.completions.create( model="hy4", messages=[{ "role": "user", "content": [ {"type": "image_url", "image_url": {"url": "YOUR_IMAGE_URL"}}, {"type": "text", "text": "请描述这张图片的内容，并说出图中有几只动物。"}, ], }],)print(response.choices[0].message.content)import base64from openai import OpenAIclient = OpenAI( api_key="YOUR_API_KEY", base_url="https://tokenhub.tencentmaas.com/v1",)# 请将 example.jpg 替换为你本地图片的路径with open("example.jpg", "rb") as f: base64_image = base64.b64encode(f.read()).decode("utf-8")response = client.chat.completions.create( model="hy4", messages=[{ "role": "user", "content": [ {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{base64_image}"}}, {"type": "text", "text": "请描述这张图片的内容，并说出图中有几只动物。"}, ], }],)print(response.choices[0].message.content)

响应示例（单图）：

{ "id": "REPLACED_ID", "object": "chat.completion", "model": "hy4", "created": 1787628534, "choices": [ { "index": 0, "message": { "role": "assistant", "content": "这张图片中有三只橘色的小猫，趴在窗台上晒太阳，背景是晴朗的天空。" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 1158, "completion_tokens": 36, "total_tokens": 1194 }}

八、多图输入

在 content 数组中并列多个 image_url 块即可实现多图输入。最大输入图片数量受上下文窗口约束，无硬性张数上限。

cURL（多图 URL）Python（多图 URL）Python（多图 Base64）curl -X POST 'https://tokenhub.tencentmaas.com/v1/chat/completions' \\ -H 'Authorization: Bearer YOUR_API_KEY' \\ -H 'Content-Type: application/json' \\ -d '{ "model": "hy4", "messages": [{"role": "user", "content": [ {"type": "image_url", "image_url": {"url": "YOUR_IMAGE_URL"}}, {"type": "image_url", "image_url": {"url": "YOUR_IMAGE_URL_2"}}, {"type": "text", "text": "请分别描述这两张图片的内容"} ]}], "stream": false }'from openai import OpenAIclient = OpenAI( api_key="YOUR_API_KEY", base_url="https://tokenhub.tencentmaas.com/v1",)response = client.chat.completions.create( model="hy4", messages=[{ "role": "user", "content": [ {"type": "image_url", "image_url": {"url": "YOUR_IMAGE_URL"}}, {"type": "image_url", "image_url": {"url": "YOUR_IMAGE_URL_2"}}, {"type": "text", "text": "请分别描述这两张图片的内容"}, ], }],)print(response.choices[0].message.content)import base64from openai import OpenAIclient = OpenAI( api_key="YOUR_API_KEY", base_url="https://tokenhub.tencentmaas.com/v1",)def load_b64(path): # 请将路径替换为你本地图片 with open(path, "rb") as f: return base64.b64encode(f.read()).decode("utf-8")# 请将 example_a.jpg / example_b.jpg 替换为你本地图片的路径image_a = load_b64("example_a.jpg")image_b = load_b64("example_b.jpg")response = client.chat.completions.create( model="hy4", messages=[{ "role": "user", "content": [ {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{image_a}"}}, {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{image_b}"}}, {"type": "text", "text": "请分别描述这两张图片的内容"}, ], }],)print(response.choices[0].message.content)

响应示例（多图）：

{ "id": "REPLACED_ID", "object": "chat.completion", "model": "hy4", "created": 1787628932, "choices": [ { "index": 0, "message": { "role": "assistant", "content": "### 第一张图片\\n- 颜色：这张图片由两种纯色组成，上半部分是蓝色（饱和度和亮度较高的正蓝色或艳蓝色），下半部分是红色（饱和度和亮度较高的正红色或艳红色）。\\n- 构图：采用了水平二分构图（上下分割），整个画面被一条水平直线（大致在图像垂直方向的中点位置）分成上下两个相等的矩形区域，上方区域填充蓝色，下方区域填充红色，两种颜色区域的面积大致相等，视觉上呈现出简洁的上下分色效果。\\n\\n\\n### 第二张图片\\n- 颜色：这张图片同样由两种纯色组成，左半部分是绿色（饱和度较高的鲜绿色或草绿色），右半部分是黄色（饱和度较高的亮黄色或柠檬黄）。\\n- 构图：采用了垂直二分构图（左右分割），整个画面被一条垂直直线（大致在图像水平方向的中点位置）分成左右两个相等的矩形区域，左侧区域填充绿色，右侧区域填充黄色，两种颜色区域的面积大致相等，视觉上呈现出简洁的左右分色效果。\\n" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 569, "completion_tokens": 231, "total_tokens": 800 }}

注意：说明：

九、支持的图片格式

支持格式为 JPEG、PNG、WEBP、非动态 GIF 四种常见图片格式。

如需使用上述四种以外的图片格式，建议在接入前自行实测验证，确认模型可正常解析后再正式使用。

十、图片数量说明

单次请求可传入的图片数量受限于所选模型的上下文窗口（Context Window）。当输入总 Token（文本 + 所有图片 + 输出）超过模型上下文窗口时，信息会被截断或请求被拒绝。

模型上下文窗口请参见 模型列表。

举例说明（以 16k 上下文窗口为例）：

·当图片分辨率较大（如 1024×1024），每张图片约消耗 1,058 token，单次请求可传入的图片数量约为：
16000 ÷ 1058 ≈ 15 张

·当图片分辨率中等（如 768×768），每张图片约消耗 602 token，单次请求可传入的数量约为：
16000 ÷ 602 ≈ 26 张

注意：说明：

注意：模型回复的质量受输入图片信息量影响。过多的图片会导致模型回复质量下降，请合理控制单次请求传入图片的数量。

十一、图片文件大小

注意：说明：