多模态 API 实战教程：只需 12 行代码，让 AI 学会看图说话

拍一张菜单发给 AI，几秒后它告诉你：

"这份菜单共 23 道菜。推荐'夫妻肺片'（¥38，微辣）和'口水鸡'（¥42，中辣），两者搭配一份'蒜泥白肉'非常经典。注意'水煮鱼'标注了大辣，怕辣的朋友慎选。"

第一次看到这个效果，大多数人的反应是："这也行？！"

更让人意外的是——实现这个效果的代码，真的只有 12 行。

2025 年，多模态 AI 已经从实验室走进了每个开发者的工具箱。GPT-4o、Claude 3.5 Sonnet、Gemini 1.5 Pro……顶级模型全面支持图像理解，能力之强、调用之简单，超出大多数人的想象。唯一的门槛，是国内用户直连 OpenAI/Anthropic 的网络障碍和支付问题。

本文的任务很简单：帮你把这个门槛彻底踢掉，然后手把手带你跑通四个由浅入深的多模态案例。

---

一、多模态 API 是什么？为什么现在就该学

"多模态"这个词听起来高深，拆开来其实很直白：AI 不再只能读文字，还能同时理解图片。

传统的文本 API，你给它一段话，它回一段话。多模态 API，你可以同时给它一张图 + 一段话，它理解图片内容后再回答。就像你把一张照片递给朋友，问他"这是什么品牌的包"，他看一眼就能告诉你——AI 现在也能做到这件事，而且往往比人更快、更准。

• GPT-4o：OpenAI 旗舰模型，视觉理解业界顶尖，支持单次请求传入多张图片
• Claude 3.5 Sonnet：Anthropic 出品，对图表、文档、代码截图的理解能力尤为突出
• Gemini 1.5 Pro：Google 出品，支持超长上下文，处理多页 PDF 截图毫不费力

这已经不是"未来技术"，而是现在就能用、用了就有产出的工程能力。

---

二、5 分钟搞定环境准备

本教程所有代码均基于 [api.884819.xyz](https://api.884819.xyz) 运行。这是一个国内可直连的 AI API 中转站，兼容 OpenAI 官方 SDK 格式，支持人民币充值，主流多模态模型全覆盖。

如果你还没有账号，现在花 1 分钟注册一个，后面的代码可以边看边跑。

注册完成后，在控制台创建一个 API Key，复制保存好。

支持的主流多模态模型对比

💡 选型建议：日常开发和测试用 GPT-4o-mini，成本低 9 倍；生产环境或对精度要求高的场景用 GPT-4o 或 Claude 3.5 Sonnet。

安装依赖

pip install openai pillow requests

# requirements.txt
openai>=1.30.0
pillow>=10.0.0
requests>=2.31.0

配置基础客户端

from openai import OpenAI

client = OpenAI(
api_key="你的_API_KEY",
base_url="https://api.884819.xyz/v1"  # 国内直连，无需科学上网
)

就这一行 base_url，把官方地址换成中转站地址，其余代码和 OpenAI 官方文档完全一致。

---

三、核心实战：四个由浅入深的案例

案例 1：入门——让 AI 描述图片内容

最基础的"看图说话"。把一张图片的 URL 传给 AI，让它描述看到了什么。

from openai import OpenAI

client = OpenAI(
api_key="你的_API_KEY",
base_url="https://api.884819.xyz/v1"
)

response = client.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://example.com/your-image.jpg",
"detail": "auto"  # auto / low / high
}
},
{
"type": "text",
"text": "请详细描述这张图片的内容。"
}
]
}
]
)

print(response.choices[0].message.content)

• content 是一个列表，可以混合 image_url 和 text 两种类型
• detail 参数控制识别精度和 token 消耗（后文避坑指南详细说明）
• 图片和文字的顺序可以任意排列，建议图片放前面

---

案例 2：实用——商品截图结构化提取

电商场景的高频需求：把商品截图丢给 AI，自动提取名称、价格、规格，输出 JSON。

import json
from openai import OpenAI

client = OpenAI(
api_key="你的_API_KEY",
base_url="https://api.884819.xyz/v1"
)

def extract_product_info(image_url: str) -> dict:
response = client.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "system",
"content": "你是一个商品信息提取助手。请从图片中提取商品信息，严格按照指定 JSON 格式输出，不要添加任何额外说明。"
},
{
"role": "user",
"content": [
{"type": "image_url", "image_url": {"url": image_url}},
{
"type": "text",
"text": """请提取图片中的商品信息，输出格式如下：
{
"name": "商品名称",
"price": "价格（含单位）",
"specs": ["规格1", "规格2"],
"brand": "品牌",
"discount": "折扣信息（无则填null）"
}"""
}
]
}
],
response_format={"type": "json_object"}  # 强制 JSON 输出
)

return json.loads(response.choices[0].message.content)

使用示例
result = extract_product_info("https://example.com/product-screenshot.jpg")
print(json.dumps(result, ensure_ascii=False, indent=2))

{
"name": "Apple AirPods Pro (第二代)",
"price": "¥1,799",
"specs": ["主动降噪", "USB-C充电", "IP54防水"],
"brand": "Apple",
"discount": "限时立减200元"
}

---

案例 3：进阶——多图对比分析

传入两张图片，让 AI 进行差异对比。典型场景：设计稿改版前后对比、两份数据图表趋势分析。

from openai import OpenAI
import base64

client = OpenAI(
api_key="你的_API_KEY",
base_url="https://api.884819.xyz/v1"
)

def encode_image_to_base64(image_path: str) -> str:
"""将本地图片转为 Base64 编码"""
with open(image_path, "rb") as f:
return base64.b64encode(f.read()).decode("utf-8")

def compare_two_images(image_path_1: str, image_path_2: str, task: str) -> str:
img1_b64 = encode_image_to_base64(image_path_1)
img2_b64 = encode_image_to_base64(image_path_2)

response = client.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "图片1（改版前）："},
{
"type": "image_url",
"image_url": {
"url": f"data:image/jpeg;base64,{img1_b64}",
"detail": "high"
}
},
{"type": "text", "text": "图片2（改版后）："},
{
"type": "image_url",
"image_url": {
"url": f"data:image/jpeg;base64,{img2_b64}",
"detail": "high"
}
},
{"type": "text", "text": task}
]
}
]
)
return response.choices[0].message.content

使用示例
result = compare_two_images(
"design_v1.jpg",
"design_v2.jpg",
"请列出两版设计稿的所有差异，包括颜色、布局、文案、图标变化，并评估哪个版本的用户体验更好。"
)
print(result)

这里用了 Base64 编码传图——适合本地图片，不需要先上传到图床。URL 和 Base64 两种方式的选择逻辑，见下一章避坑指南。

---

案例 4：高阶——智能看图客服

结合 System Prompt，构建一个完整的"看图客服"：用户上传图片提问，AI 基于图片内容 + 预设知识库进行专业回答。

from openai import OpenAI
import base64
from pathlib import Path

client = OpenAI(
api_key="你的_API_KEY",
base_url="https://api.884819.xyz/v1"
)

SYSTEM_PROMPT = """你是一位专业的家电售后客服，专门处理用户上传的产品图片问题。

你的工作流程：
1. 仔细观察用户上传的图片，识别产品型号、故障现象或使用场景
2. 基于图片内容给出专业判断
3. 提供具体的解决方案或操作步骤
4. 如需返修，告知用户联系方式：400-888-8888

注意事项：
始终保持专业、耐心的态度
如果图片不够清晰，礼貌地请用户重新拍摄
不要猜测图片中没有显示的信息
"""

class VisualCustomerService:
def __init__(self):
self.conversation_history = [
{"role": "system", "content": SYSTEM_PROMPT}
]

def chat_with_image(self, user_text: str, image_path: str = None) -> str:
content = []

if image_path and Path(image_path).exists():
with open(image_path, "rb") as f:
img_b64 = base64.b64encode(f.read()).decode("utf-8")
suffix = Path(image_path).suffix.lower().replace(".", "")
mime = f"image/{'jpeg' if suffix == 'jpg' else suffix}"
content.append({
"type": "image_url",
"image_url": {
"url": f"data:{mime};base64,{img_b64}",
"detail": "high"
}
})

content.append({"type": "text", "text": user_text})
self.conversation_history.append({"role": "user", "content": content})

response = client.chat.completions.create(
model="gpt-4o",
messages=self.conversation_history,
max_tokens=1000
)

assistant_reply = response.choices[0].message.content
self.conversation_history.append({
"role": "assistant",
"content": assistant_reply
})
return assistant_reply


使用示例
service = VisualCustomerService()

第一轮：用户上传图片
reply1 = service.chat_with_image(
"我的洗衣机显示屏出现了这个错误代码，请问是什么问题？",
image_path="washer_error.jpg"
)
print("客服：", reply1)

第二轮：追问（无需重复上传图片，上下文已保留）
reply2 = service.chat_with_image("需要自己修还是找上门服务？")
print("客服：", reply2)

这个案例的核心亮点是多轮对话 + 图片上下文保留。用户第一轮上传图片，第二轮追问时 AI 依然记得图片内容，无需重复上传。

---

四、避坑指南——8 个关键细节

1. URL 传图 vs Base64 传图，怎么选？

2. detail 参数的 Token 消耗差异

这是成本控制最关键的参数，很多人忽视了它：

3. 成本估算——以每天处理 100 张商品图为例

对于商品图批量处理，GPT-4o-mini + detail:low 是性价比最高的组合，月度成本不到 2 元。

4. 图片预处理工具函数

from PIL import Image
import io
import base64

def preprocess_image(image_path: str, max_size: int = 2048) -> str:
"""压缩图片并转为 Base64，避免超出限制"""
img = Image.open(image_path)

# 转为 RGB（处理 PNG 透明通道）
if img.mode in ("RGBA", "P"):
img = img.convert("RGB")

# 等比例缩放
if max(img.size) > max_size:
ratio = max_size / max(img.size)
new_size = (int(img.width  ratio), int(img.height  ratio))
img = img.resize(new_size, Image.LANCZOS)

buffer = io.BytesIO()
img.save(buffer, format="JPEG", quality=85)
return base64.b64encode(buffer.getvalue()).decode("utf-8")

5. 常见报错速查表

6. 中文场景 Prompt 优化技巧

• 明确告诉模型"图片中的文字是中文"，识别准确率提升明显
• 要求输出中文时，在 System Prompt 中加"请始终用中文回答"
• 处理中文菜单、发票、名片时，加上"请注意识别简体/繁体中文字符"

---

五、真实应用场景——多模态 API 能帮你做什么

学完技术，更重要的是想清楚用它做什么。

---

多模态 AI 的能力边界，取决于你给它看什么。

你现在已经掌握了从基础调用到完整应用的全套技能。注册 [api.884819.xyz](https://api.884819.xyz) 账号，复制上面的代码，5 分钟就能跑出你的第一个"看图说话"应用。

本文所有代码均已测试通过，基于 api.884819.xyz 可直接运行。

---

### 📌 下期预告

>

学会了让 AI 看图，下一步自然是——让 AI 看视频。

>

下一篇文章，我们将深入视频理解 API 实战：如何让 AI 分析一段视频的完整内容、自动提取关键帧、生成视频摘要，甚至为你的短视频自动写脚本。从抖音内容分析到会议录像摘要，视频多模态的爆发力比图片更炸裂——而实现它的代码，依然不超过 50 行。

>

关注我们，下周见。

---