厂商兼容说明

阿里百炼、火山方舟、腾讯混元都支持 OpenAI SDK 接入，但高级参数与多模态能力以具体厂商和模型文档为准。

统一接入，不等于每个模型支持完全相同的字段

Swarmix 保持统一的 base_url、api_key 和 OpenAI-compatible 请求结构。模型是否支持视觉、工具调用、JSON 输出、长上下文、思考模式、文件输入等能力，取决于你选择的 model 和上游厂商文档。

客户侧稳定契约

常规文本对话优先使用 /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 结构化输出等新字段可以提交给平台，但生产环境应先按模型验证。

三家厂商对照

厂商	推荐接入方式	适合直接依赖的能力	需要注意
阿里百炼	OpenAI 兼容模式，官方示例使用 `https://dashscope.aliyuncs.com/compatible-mode/v1`。	文本、流式、视觉模型、部分工具与厂商扩展参数。	Qwen 系列经常存在模型级差异；联网搜索、代码解释器、思考模式等能力通常需要按阿里文档传 `extra_body` 或厂商扩展字段。
火山方舟	OpenAI 兼容请求，生产场景常使用方舟推理接入点或模型 ID。	文本、流式、Doubao 系列多模态模型、常规工具调用。	部分高级字段在文档中未统一声明；需要固定火山模型能力时，建议使用 `provider.only` 并开启 `require_parameters`。
腾讯混元	OpenAI 兼容接口，官方示例使用 `https://api.hunyuan.cloud.tencent.com/v1`。	文本、流式、视觉模型、`tools` / `tool_choice`。	官方角色列表以 `system`、`user`、`assistant`、`tool` 为主；`developer` 与 `strict` 不应假设所有腾讯模型都支持。

多模态请求建议

图片理解、视频理解、文件输入最容易出现厂商差异。Swarmix 会保留 OpenAI-compatible 请求结构并转发给上游，但图片尺寸、URL 可访问性、Base64 支持、视频时长、文件类型和上下文长度都以厂商文档为准。

python

from openai import OpenAI

client = OpenAI(
    api_key="sk-swx-xxxxxxxxxxxxxxxxxxxx",
    base_url="http://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 的模型列表中查看模型所属厂商、上游模型名和官方文档链接。上线前用 Playground 或测试环境 API Key 验证一次真实请求，并在请求日志中确认路由到的 provider、延迟、错误码和 token 用量。

← 上一篇

流式响应处理

常见问题