MixSo Open Platform 开发者文档

快速开始

保留现有 OpenAI 兼容代码，只替换 Base URL 和 API Key。标准调用不需要 MixSo 专属 SDK 包。

Base URLhttps://open.mixsoai.com/v1

API KeyAuthorization: Bearer YOUR_MIXSO_API_KEY

EndpointPOST /chat/completions

curl https://open.mixsoai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MIXSO_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {
        "role": "user",
        "content": "Hello from MixSo Open Platform"
      }
    ]
  }'

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_MIXSO_API_KEY",
    base_url="https://open.mixsoai.com/v1"
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {
            "role": "user",
            "content": "Hello from MixSo Open Platform"
        }
    ]
)

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

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MIXSO_API_KEY,
  baseURL: "https://open.mixsoai.com/v1"
});

const response = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [
    {
      role: "user",
      content: "Hello from MixSo Open Platform"
    }
  ]
});

console.log(response.choices[0].message.content);

SDK 包： MixSo 提供 API 调用示例。你可以使用任意兼容客户端，并配置 Base URL 和 API Key。

认证方式

所有 API 请求使用 Bearer 认证。请在控制台创建 API Key，将生产 Key 保存在服务端，并按需轮换。

项目	值	说明
Header	`Authorization`	每个 API 请求都需要。
Format	`Bearer sk-xxxxxx`	使用你的 MixSo API Key。
Base URL	`https://open.mixsoai.com/v1`	OpenAI 兼容接口根路径。

生产安全： 不要在浏览器 JavaScript、公开仓库、移动端、日志或截图中暴露 API Key。

Chat Completions

使用 POST /v1/chat/completions 处理对话、代码助手、摘要、分类、抽取、工具调用和多轮工作流。

参数	类型	说明
`model`	string	MixSo 控制台中启用的模型标识。
`messages`	array	使用 role 和 content 组成的对话消息。
`temperature`	number	模型支持时用于控制随机性。
`stream`	boolean	设置为 true 可启用增量输出。
`tools`	array	兼容模型可用的工具定义。
`response_format`	object	仅在所选模型支持时使用。

视觉输入

对于兼容模型，可以在 user message 中同时传入文本和图片内容。请根据启用模型使用图片 URL 或支持的图片载荷格式。

cURL

curl https://open.mixsoai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MIXSO_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Describe this product image."
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://example.com/product.png"
            }
          }
        ]
      }
    ]
  }'

流式输出

将 stream 设置为 true 可以接收增量输出。适用于聊天界面、代码 Agent 和长响应。

cURL

curl https://open.mixsoai.com/v1/chat/completions \
  -H "Authorization: Bearer $MIXSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": "Write a concise product description."
      }
    ]
  }'

Embeddings

Embeddings 可将文本转换为向量，用于搜索、检索、聚类和 RAG 工作流。模型可用性和向量维度取决于所选 embedding 模型。

cURL

curl https://open.mixsoai.com/v1/embeddings \
  -H "Authorization: Bearer $MIXSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-model",
    "input": "MixSo Open Platform developer documentation"
  }'

模型

模型访问由 MixSo 控制台配置管理。发送请求时请使用控制台展示或模型接口返回的模型 ID。

cURL

curl https://open.mixsoai.com/v1/models \
  -H "Authorization: Bearer $MIXSO_API_KEY"

能力	示例用途	说明
Chat	通用助手、写作、代码	使用控制台启用的聊天模型。
Vision	图片分析和多模态输入	取决于模型。
Embeddings	搜索、RAG、聚类	维度取决于模型。

错误说明

调试时，请优先检查请求 ID、状态码、所选模型、账号额度和控制台请求日志。

Status	含义	建议操作
400	请求体无效或参数不支持。	检查模型兼容性和载荷格式。
401	API Key 缺失或无效。	检查 Authorization 请求头。
429	频率、额度或账号用量问题。	检查额度、余额和重试策略。
503	模型服务暂不可用。	短暂间隔后重试，或选择其他兼容模型。

路由概览

路由定义 MixSo 如何为请求选择可用模型路径。应用发送稳定模型 ID，MixSo 根据控制台配置、路径可用性、模型兼容性和故障保护规则处理供应商侧路由。

应用代码稳定应用代码中保持稳定模型 ID，在控制台中调整供应商和路由。

运营可观测通过日志查看命中的路由、错误、延迟和用量详情。

请求路由

请求进入后，MixSo 会评估账号权限、模型 ID、参数兼容性、路由健康、额度和故障保护选项。

校验 API Key 和账号状态。
将公开模型 ID 解析到已启用路径。
检查所选模型的参数兼容性。
将请求发送到最佳可用路径。
记录用量日志和计费字段。

故障保护

当模型路径暂不可用时，故障保护可以增强生产应用稳定性。符合条件的路径失败后，MixSo 可根据配置策略重试其他兼容路径。

项目	说明
重试策略	控制路径失败后是否允许重试。
兼容性门槛	故障保护只使用与模型和参数兼容的路径。
日志	用量日志展示最终路径、状态和错误详情。

参数兼容

大多数标准对话参数表现一致，但可选能力可能随模型变化。生产使用前应确认高级参数。

参数	需要确认
`tools`	所选模型支持工具调用。
`response_format`	模型支持 JSON mode 或 JSON Schema 输出。
`stream_options`	模型支持时，流式响应可返回用量详情。
`reasoning`	所选模型支持推理控制参数。

cURL 示例

集成客户端应用前，可先用 cURL 快速验证。

curl https://open.mixsoai.com/v1/chat/completions \
  -H "Authorization: Bearer $MIXSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {
        "role": "user",
        "content": "Ping"
      }
    ]
  }'

curl https://open.mixsoai.com/v1/chat/completions \
  -H "Authorization: Bearer $MIXSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": "Stream a short answer"
      }
    ]
  }'

curl https://open.mixsoai.com/v1/models \
  -H "Authorization: Bearer $MIXSO_API_KEY"

Python 示例

使用 OpenAI 兼容 Python 客户端并设置 MixSo 接口地址。

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_MIXSO_API_KEY",
    base_url="https://open.mixsoai.com/v1"
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {
            "role": "user",
            "content": "Explain MixSo in one sentence."
        }
    ]
)

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

Node.js 示例

使用现有兼容 JavaScript 客户端，并设置 MixSo Base URL。

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MIXSO_API_KEY,
  baseURL: "https://open.mixsoai.com/v1"
});

const response = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [
    {
      role: "user",
      content: "Explain MixSo in one sentence."
    }
  ]
});

console.log(response.choices[0].message.content);

Cursor 配置

对于支持自定义 OpenAI 兼容 Provider 的客户端，可以将 MixSo 配置为 API Provider。部分客户端功能可能继续使用其内置模型。

在控制台创建 MixSo API Key。
将 Base URL 设置为 https://open.mixsoai.com/v1。
选择账号中已启用的模型 ID。
用简短聊天请求验证。

Claude Code 配置

如果客户端支持 OpenAI 兼容自定义端点，可使用 MixSo Base URL 和 API Key。模型 ID 应与控制台配置保持一致。

兼容性提示： 部分客户端专属功能可能需要特定供应商。MixSo 用于支持的标准模型请求。

OpenCode 配置

自定义 Provider 配置中，创建一个包含 MixSo Base URL 和 API Key 的 Provider，并映射所需模型 ID。

JSON

{
  "provider": {
    "mixso": {
      "baseURL": "https://open.mixsoai.com/v1",
      "apiKey": "{env:MIXSO_API_KEY}",
      "models": {
        "gpt-5.5": {}
      }
    }
  }
}

LiteLLM 配置

对于 LiteLLM 或网关类客户端，可使用 MixSo Base URL 和 Key 配置 OpenAI 兼容自定义 Provider。

YAML

model_list:
  - model_name: mixso-gpt-5-5
    litellm_params:
      model: openai/gpt-5.5
      api_base: https://open.mixsoai.com/v1
      api_key: os.environ/MIXSO_API_KEY

控制台

通过控制台创建 API Key、管理模型访问、查看请求日志、监控失败、查看计费详情。

✓为开发、测试、生产分别创建不同 Key。

✓调试模型或路由问题时查看请求日志。

✓Key 可能泄露时及时轮换。

计费与用量

用量和计费可在控制台查看。可按 Key、模型、时间、状态和费用字段追踪请求。

用量控制： 生产上线前设置用量提醒或运营限制。

故障排查

大多数接入问题可以通过认证、模型可用性、请求参数、路由健康和账户余额定位。

问题	检查项
401	API Key 格式、Authorization 请求头、Key 状态。
429	频率限制、额度、余额、重试行为。
Model unavailable	模型访问、路由状态、故障保护策略。
Streaming interrupted	客户端超时、网络代理、流式解析。