模型提供方兼容说明

客户侧稳定契约

• 常规文本对话优先使用 /v1/chat/completions、messages、stream、temperature、top_p、max_tokens。
• 视觉理解使用 OpenAI 格式的 content parts：text + image_url，并选择明确支持视觉的模型。
• 工具调用使用新版 tools / tool_choice，不要再使用旧版 functions / function_call。
• developer role、response_format、strict 结构化输出等新字段可以提交给平台，但生产环境应先按模型验证。 注：以下字段说明会按模型提供方维度组织，便于你对照各模型的能力差异。

按模型提供方对照

所有模型提供方都通过统一的 Swarmix 接入点访问，base_url 始终是 https://router.swarmixtoken.com/v1，无需为不同模型切换地址。下表按 模型提供方维度列出可直接依赖的能力与注意事项。

多模态请求建议

图片理解、视频理解、文件输入最容易出现模型间差异。Swarmix 会保留 OpenAI-compatible 请求结构并转发到对应模型，但图片尺寸、URL 可访问性、Base64 支持、视频时长、文件类型和上下文长度都以所选模型的能力为准。

from openai import OpenAI

client = OpenAI(
    api_key="sk-swx-xxxxxxxxxxxxxxxxxxxx",
    base_url="https://router.swarmixtoken.com/v1",
)

resp = client.chat.completions.create(
    model="qwen3-vl-plus",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "image_url", "image_url": {"url": "https://example.com/image.png"}},
                {"type": "text", "text": "请描述这张图片"},
            ],
        }
    ],
    # 可选：需要固定模型提供方时再使用 provider 路由控制
    extra_body={
        "provider": {
            "only": ["aliyun"],
            "allow_fallbacks": False,
            "require_parameters": True,
        }
    },
)

高级参数怎么用

developer role

平台会接受 developer role。为了最大兼容性，跨厂商生产流量仍建议优先使用 system；只有在确认目标模型支持时，再依赖 developer 的语义。

strict / 结构化输出

tools[].function.strict 和 response_format 属于结构化输出相关能力。 平台会尽量保留字段，但模型是否严格遵守 JSON Schema 由模型本身决定。生产环境必须用真实模型做回归测试。

固定模型提供方路由

如果你的业务依赖某个模型提供方的专有能力，不要允许容错处理切到其它提供方。使用 provider.only、allow_fallbacks=false 和 require_parameters=true 可以把不兼容问题提前暴露。

能力查询入口

• 在 Console 的模型列表中查看每个公开模型 ID 支持的能力（视觉、工具调用、结构化输出、上下文长度等）。
• 通过 /v1/models 接口按模型提供方分组拉取可用模型及其能力标记。
• 在 Playground 中直接验证某个模型对高级字段的实际支持情况。