Ling-3.2-flash 接入实操：图文视频混输、双协议差异与六个必踩的关卡

蚂蚁百灵 11 月 6 日发布 Ling-3.2-flash，560B 总参数 / 25B 激活 / 1M 上下文，原生接受文本、图像与视频输入，同时提供 OpenAI 与 Anthropic 两套兼容协议。本文只讲一件事：从零拼出一个能跑的请求，逐层把图片、视频、长上下文、工具调用加进去，每一层会遇到什么限制。

所有命令与字段均依据官方文档整理，未在本文环境实际发起调用。Key 全部为占位符，接入前建议在测试环境先跑一遍第十一节的探测脚本。

一、从一个必然失败的请求说起

按 OpenAI 生态的习惯写法，把一张公网图片塞进 image_url，这是最常见的第一行代码：

{
  "model": "Ling-3.2-flash",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/a.png"}},
      {"type": "text", "text": "描述这张图"}
    ]
  }]
}

这个请求跑不通。官方多模态文档写得很明确：图片、视频、音频输入一律只接受 Base64 编码，不走公网 URL（Inputs are passed via Base64 encoding only）。image_url 这个字段名保留了下来，但 url 的值必须是 data:{MIME_TYPE};base64,<原始 Base64 串>。

这类"字段名看着像 OpenAI、取值规则却不是 OpenAI"的地方，在这次接入里不止一处。下面按一个请求从外到内的装配顺序，逐关拆开。

二、开工前的三项确认

动笔写代码前，有三件事必须先定，否则后面每一层都会返工。第一节是引子，从第三节起按第 1 关到第 6 关逐层装配。

第一，这一代是 API-only，权重尚未开放。 官方模型文档只标注 Ling-3.0-flash-VL 已在 Hugging Face 与 ModelScope 开源、Ling-3.0-tiny “will be open-sourced in the near future”，对 Ling-3.2-flash 没有给出开源说明。媒体口径是"权重将在近期开放"【交叉】。所以本次能做的是调 API，不是本地部署。

第二，模型 ID 大小写敏感，写成 ling-3.2-flash 不在选项列表里。 官方给出的可选项是：

表中"未提及"是文档没有声明支持，不等于确认不支持。另外 Ling-3.0-flash-VL 的 42 层混合架构（KDA 与 Gated MLA 按 5:1 交替）、任意分辨率视觉编码器、VideoRoPE 这些描述都属于 3.0-flash-VL，不要套到 3.2-flash 头上。

第三，两个协议是两个地址，不是同一个地址的两种参数。

三、第 1 关：认证 header 的"恰好一个"

OpenAI 协议只用一种：

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

Anthropic 协议给了两种，但文档原文是 “either Authorization or x-api-key can be used — exactly one is required”：

# 方案 A
Authorization: Bearer <YOUR_API_KEY>

# 方案 B
x-api-key: <YOUR_API_KEY>

"恰好一个"意味着两个都传不符合规范。 用 Anthropic 官方 SDK 时，SDK 默认会同时塞 x-api-key 和 anthropic-version；如果又手动在 default_headers 里补了 Authorization，就变成两个认证头。接之前先确认 SDK 实际发出的 header，不要叠加。

Key 的获取入口是 API Console 的 Create Token（https://chat.ant-ling.com/open）。文档示例里出现的 sk-studio-xx 是占位格式，不是可直接抄的 Key。

四、第 2 关：最小可跑请求与 90 秒超时

先用纯文本把链路打通。这是官方流式示例的原文形态：

curl --request POST \
  --url https://api.ant-ling.com/v1/chat/completions \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "Ling-3.2-flash",
  "stream": true,
  "messages": [
    {"role": "user", "content": "用三句话说明 MoE 的路由机制"}
  ]
}'

用 OpenAI SDK 时把 base_url 指过去即可：

from openai import OpenAI

client = OpenAI(
    base_url="https://api.ant-ling.com/v1",
    api_key="YOUR_API_KEY",
)

resp = client.chat.completions.create(
    model="Ling-3.2-flash",
    messages=[{"role": "user", "content": "用三句话说明 MoE 的路由机制"}],
    stream=True,
)
for chunk in resp:
    if not chunk.choices:
        continue
    print(chunk.choices[0].delta.content or "", end="", flush=True)

这一关有三个必须知道的默认值：

thinking 是对象不是字符串，写法是：

{"thinking": {"type": "disabled"}}

这一点和 11 月初那批国产模型 API 的 reasoning_effort 七种档位完全不同：这里只有开/关两档，没有 low、medium、max，也没有 no_think。把别家的档位串直接搬过来会报参数错误。

一处文档口径差异：模型选型页没有给 Ling-3.2-flash 标注 thinking 开关，但 OpenAI 与 Anthropic 两份 API 参考都明确写 thinking 支持 3.0 / 3.1 / 3.2 系列。【官方，两页表述不一致】按 API 参考为准，并在自己环境里验证一次生效与否。

五、第 3 关：图片只能走 Base64

content 从字符串变成数组，图片块用 image_url，url 必须是 data URI：

curl --location --request POST 'https://api.ant-ling.com/v1/chat/completions' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "model": "Ling-3.2-flash",
    "stream": true,
    "messages": [{
      "role": "user",
      "content": [
        {"type": "image_url", "image_url": {"url": "data:image/png;base64,<BASE64>"}},
        {"type": "text", "text": "描述这张图里的表格结构"}
      ]
    }]
  }'

Python 侧构造这个块：

import base64
from pathlib import Path

def image_block(path: str, mime: str = "image/png") -> dict:
    raw = Path(path).read_bytes()
    b64 = base64.b64encode(raw).decode("ascii")
    return {
        "type": "image_url",
        "image_url": {"url": f"data:{mime};base64,{b64}"},
    }

content = [image_block("./table.png"), {"type": "text", "text": "描述这张图里的表格结构"}]

这一关的硬限制（全部来自官方文档，照录）：

有三处容易踩：

1. Base64 会膨胀约 1/3。 请求体上限是 32 MiB 的编码后体积，对应原始二进制约 24 MiB【推算：32 × 3/4 ≈ 24】。多图叠加时注意总量，不是"每张都不超 32 MiB 就行"，40 张图同时达到单张上限是不可能的。
2. image_url.detail 不被支持。 官方文档把它列在 Unsupported Properties 里，并说明推理引擎按 default 处理。OpenAI 生态里常用的 detail: "high" 传了不会生效，别指望用它调分辨率。
3. 官方多模态示例的 model 写的是 Ling-3.0-flash-VL。 示例代码不能直接整段复制，要改成 Ling-3.2-flash。这一步漏了不会报错，只是调到了另一个模型上。

六、第 4 关：视频的 30 秒与 32 帧

视频块换成 video_url，结构和图片同形：

{
  "type": "video_url",
  "video_url": {"url": "data:video/mp4;base64,<BASE64_VIDEO>"}
}

完整请求：

curl --location --request POST 'https://api.ant-ling.com/v1/chat/completions' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "model": "Ling-3.2-flash",
    "stream": true,
    "messages": [{
      "role": "user",
      "content": [
        {"type": "video_url", "video_url": {"url": "data:video/mp4;base64,<BASE64_VIDEO>"}},
        {"type": "text", "text": "按时间顺序列出画面里出现的操作步骤"}
      ]
    }]
  }'

这里有一处值得单独算的覆盖问题：30 秒 × 2fps = 60 帧，而上限是 32 帧。 如果按固定的 2fps 从头顺序抽帧，32 帧只能覆盖前 16 秒；要覆盖满 30 秒，实际采样率得降到约 1.07fps，与"固定 2fps"的表述不一致【推算，基于官方两个数字相除】。

官方文档没有说明超限后是截断尾部、均匀重采样，还是直接拒绝【未披露】。稳妥做法是：把要分析的片段控制在 16 秒以内，或者按关键片段切开分多次请求，不要默认 30 秒视频的尾部内容一定被看到。这个边界对"长视频分析"这类宣传场景影响很直接。

七、第 5 关：切到 Anthropic 协议要改的五处

Anthropic 协议不是"换个 URL 就行"，请求体有五处结构性差异。

curl --request POST \
  --url https://api.ant-ling.com/anthropic/v1/messages \
  --header 'x-api-key: <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "Ling-3.2-flash",
  "max_tokens": 32000,
  "stream": true,
  "system": [{"type": "text", "text": "输出使用简体中文，先给结论"}],
  "messages": [
    {"role": "user", "content": "对比两套协议的请求体差异"}
  ]
}'

差异一：系统提示词的位置。 OpenAI 协议里 system 是 messages 里的一条（role: system）；Anthropic 协议里 messages.role 的可选项只有 user 和 assistant，系统提示必须放顶层 system 数组，元素形如 {"type": "text", "text": "..."}。把 role: system 塞进 Anthropic 的 messages 不在选项内。

差异二：输出长度参数名。

这是官方文档自身的一处不一致：OpenAI 参考页的完整参数表没有这两个字段，但多模态教程的示例里用了 max_completion_tokens。【官方，两页表述不一致】不要在 OpenAI 协议下依赖 max_tokens 生效；先在探测脚本里发一次带该字段的请求，看是否被静默忽略。

差异三：图片内容块的形状。 Anthropic 协议用 image + source，不是 image_url：

{
  "type": "image",
  "source": {
    "type": "base64",
    "media_type": "image/png",
    "data": "<BASE64_不带前缀>"
  }
}

注意 data 字段是不带 data:image/png;base64, 前缀的纯 Base64 串，与 OpenAI 协议里带 data URI 的 url 正好相反。这是切换协议时最容易照抄错的一处。

差异四：能力矩阵不同。 官方多模态文档写明：

也就是说，音频只能走 OpenAI 协议；Ling-3.0-flash-VL 的视频输入在 Anthropic 协议下没有声明支持。Anthropic 参考页的 model 选项列表是 6 个，比 OpenAI 页的 7 个少了 Ming-3.0-audio-flash，两页能互相对上。

差异五：工具与联网参数。 OpenAI 协议有 enable_search / search_options.forced_search、tools；Anthropic 协议有 tools / tool_choice / stop_sequences，但没有 enable_search。

// OpenAI 协议：强制联网搜索
{
  "model": "Ling-3.2-flash",
  "enable_search": true,
  "search_options": {"forced_search": true},
  "messages": [{"role": "user", "content": "查一下今天蚂蚁百灵的更新"}]
}

// Anthropic 协议：工具策略
{
  "model": "Ling-3.2-flash",
  "tool_choice": {"type": "auto"},
  "tools": [{
    "name": "get_weather",
    "description": "查询城市天气",
    "input_schema": {
      "type": "object",
      "properties": {"city": {"type": "string"}},
      "required": ["city"]
    }
  }],
  "messages": [{"role": "user", "content": "广州今天天气"}]
}

enable_search 官方注明会增加 Token 消耗，按需开启；tool_choice 的四档是 auto（模型决定）/ any（必须调用）/ tool（指定工具）/ none（禁用）。

八、第 6 关：流式响应怎么拼

两套协议的 SSE 格式完全不同，拼接逻辑不能共用。

OpenAI 协议：每行 data: {...}，文本在 choices[0].delta.content，choices 可能是空数组，最后一个 choices: [] 的 chunk 才带 usage。

def consume_openai_sse(resp):
    text_parts, usage = [], None
    for chunk in resp:
        if not chunk.choices:
            if getattr(chunk, "usage", None):
                usage = chunk.usage
            continue
        text_parts.append(chunk.choices[0].delta.content or "")
    return "".join(text_parts), usage

官方流式示例里第一个 chunk 的 content 就是空字符串，中间 chunk 也可能为空；不做 or "" 兜底会拼出 None。usage 不要从中间 chunk 取——示例里中间那些都是 null，只有末尾 choices: [] 的那条才有数值，再后面还有一条 metadata: {} 的收尾 chunk。

Anthropic 协议：event: 与 data: 成对出现，文本在 content_block_delta 的 delta.text，usage 在 message_delta 里，以 message_stop 结束。

def consume_anthropic_sse(lines):
    text_parts, usage = [], None
    event = None
    for line in lines:
        if line.startswith("event:"):
            event = line[6:].strip()
        elif line.startswith("data:"):
            import json
            d = json.loads(line[5:].strip())
            if event == "content_block_delta":
                text_parts.append(d.get("delta", {}).get("text", ""))
            elif event == "message_delta":
                usage = d.get("usage")
            elif event == "message_stop":
                break
    return "".join(text_parts), usage

九、1M 上下文不是"一次塞满"

Ling-3.2-flash 的上下文窗口标称 1M，官方描述是"支持长文档与长视频分析"，并称"信息位于头部、中部或尾部都能稳定召回"。但文档没有给出最大输出长度、也没有给出 1M 下的 token 计费与限流规则【未披露】。

实操上要注意三点：

1. 输入侧硬限制仍然存在。 图片最多 40 张 / 请求、视频 1 个 / 请求且 ≤30 秒、请求体 ≤32 MiB。1M 是上下文窗口，不是放宽这些输入约束。长视频要靠分段多次请求再汇总，不是把 2 小时视频塞进一次调用。
2. 长文本与多模态混输时，content 必须是数组。 官方文档 messages.content 的类型标为 string，但多模态教程全部用数组形式的内容块。【官方，两页表述不一致】纯文本用字符串没问题；一旦混入 image_url / video_url，整条 content 就要改成块数组，文本也改成 {"type": "text", "text": "..."}，不能混着写。
3. 先开流式。 长上下文任务生成时间容易超过非流式的 90 秒上限，stream: true 是必需项而非优化项。

十、双协议完整对照表

选择判据：已有 OpenAI SDK 代码、要传视频或音频、要联网搜索 → 走 OpenAI 协议；已有 Anthropic SDK / Claude Code 类工具链、要用 tool_choice 精细控制、要用 stop_sequences → 走 Anthropic 协议。两套协议的模型 ID 相同，Key 也通用，迁移成本主要在请求体形状。

十一、可复现的探测脚本

下面这段脚本不依赖任何第三方 SDK，只发最小请求，逐项验证环境是否通、协议是否认、参数是否生效。把 YOUR_API_KEY 换掉即可运行。

import json, os, urllib.request, urllib.error

KEY = os.environ.get("ANT_LING_KEY", "YOUR_API_KEY")
OPENAI_URL = "https://api.ant-ling.com/v1/chat/completions"
ANTHROPIC_URL = "https://api.ant-ling.com/anthropic/v1/messages"

def post(url, payload, use_x_api_key=False):
    headers = {"Content-Type": "application/json"}
    if use_x_api_key:
        headers["x-api-key"] = KEY
    else:
        headers["Authorization"] = f"Bearer {KEY}"
    req = urllib.request.Request(
        url, data=json.dumps(payload).encode("utf-8"),
        headers=headers, method="POST")
    try:
        with urllib.request.urlopen(req, timeout=30) as r:
            return r.status, r.read().decode("utf-8")[:400]
    except urllib.error.HTTPError as e:
        return e.code, e.read().decode("utf-8")[:400]
    except Exception as e:
        return "ERR", str(e)

cases = [
    ("OpenAI 纯文本", OPENAI_URL,
     {"model": "Ling-3.2-flash", "stream": False,
      "messages": [{"role": "user", "content": "回复 OK 两个字符"}]}, False),
    ("OpenAI 关闭思考", OPENAI_URL,
     {"model": "Ling-3.2-flash", "stream": False, "thinking": {"type": "disabled"},
      "messages": [{"role": "user", "content": "回复 OK"}]}, False),
    ("OpenAI max_completion_tokens 是否被接受", OPENAI_URL,
     {"model": "Ling-3.2-flash", "stream": False, "max_completion_tokens": 64,
      "messages": [{"role": "user", "content": "回复 OK"}]}, False),
    ("Anthropic Bearer", ANTHROPIC_URL,
     {"model": "Ling-3.2-flash", "stream": False, "max_tokens": 64,
      "messages": [{"role": "user", "content": "回复 OK"}]}, False),
    ("Anthropic x-api-key", ANTHROPIC_URL,
     {"model": "Ling-3.2-flash", "stream": False, "max_tokens": 64,
      "messages": [{"role": "user", "content": "回复 OK"}]}, True),
]

for name, url, payload, xk in cases:
    code, body = post(url, payload, xk)
    print(f"{name:38s} -> {code}  {body[:120]}")

脚本的用途是验证参数是否被接受，不是测速度或跑分。三个需要特别看的返回：

• 第 3 项若返回 200 且响应里出现输出长度被限制的效果，说明 max_completion_tokens 在 OpenAI 协议下生效；若字段被静默忽略，不会报错，只能靠对比输出长度判断。
• 第 4、5 项应都返回 200，用来确认两种认证头都可用；再手动加一个"两个都传"的用例，观察服务端是否拒绝，验证"恰好一个"这条约束的实际行为。
• 若第 1 项就返回 401，先查 Key 前缀与控制台 Token 是否一致，不要急着改请求体。

脚本的局限：它只用纯文本，不覆盖 Base64 图片/视频的体积与格式校验；未知参数是否被静默忽略也因模型实现而异，探测结果只能说明当前版本的行为，不能当作长期契约。官方在仓库里用全大写标注过兼容层可能变化，升级后建议重跑。

十二、排查清单

十三、边界与未披露清单

以下项目在官方模型文档与 API 参考中均没有给出数值或条款，任何具体说法都只能标为外部口径，接入时不要假设：

另外两处官方文档内部不一致，本文按 API 参考页优先、并建议自行探测：

1. messages.content 类型标为 string，但多模态教程全用块数组。
2. OpenAI 参考页参数表没有输出长度字段，多模态示例却用 max_completion_tokens。

这两处属于文档维护滞后，不是模型缺陷，但照着抄会写出跑不通的代码。

十四、结论：三个可直接落地的判断

第一，图片与视频一律先转 Base64，不要试公网 URL。 这是与 OpenAI 生态差别最大、也最容易在第一行代码上就失败的一处。

第二，切协议时改的是请求体形状，不只是 URL。 系统提示位置、输出长度参数名、图片块的 data 是否带前缀、模型选项列表，四项都要跟着改；音频和 Ling-3.0-flash-VL 的视频在 Anthropic 协议下没有声明支持。

第三，长任务默认开流式。 非流式 90 秒超时是硬约束，1M 上下文、多图、长生成任务都在这条线之外。

这套接入的价值在于同一个模型 ID、同一把 Key、两套生态工具链可以直接复用：OpenAI SDK 与 Anthropic SDK 都不用改代码结构，只要换 base_url 与请求体形状。对已经有一套 Claude / OpenAI 工具链、想切到国产多模态模型的团队，迁移成本主要在本文第七节那张对照表，而不在模型本身。