Xiaoya Open Platform

简体中文

English

简体中文

English

深色模式

模型目录与调用 ​

开放智能体可以使用 OAuth Token 查询当前用户或 Team 真正可用的模型，然后通过小雅统一模型网关调用。底层供应商密钥、上游地址和内部路由不会返回给开发者。

获取 Personal 模型目录 ​

需要 model Scope 和 Personal-bound Token：

http
GET /api/v1/open/models
Authorization: Bearer <personal-access-token>
Accept: application/json

每个模型包含稳定的 modelCode、展示名、模型类型、输入输出能力、参数 Schema 版本和 parameterSpec。

成功响应示例：

json
{
  "success": true,
  "data": [
    {
      "modelCode": "othan-2.0",
      "displayName": "Othan 2.0",
      "modelType": "chat",
      "inputsText": true,
      "inputsImage": true,
      "outputsText": true,
      "structuredOutputMode": "prompt",
      "outputsImage": false,
      "parameterSchemaVersion": 1,
      "parameterSpec": {
        "temperature": { "type": "number", "minimum": 0, "maximum": 2 }
      }
    }
  ],
  "request_id": "req_01"
}

JSON 结构化输出能力 ​

Personal 与 Team 目录项的 structuredOutputMode 声明可用的文本输出模式：

值调用方式
prompt在提示词中描述 JSON 格式；不请求原生 response_format。
json_object可发送 response_format: { "type": "json_object" }，要求返回 JSON 对象。
json_schema可发送 response_format.type: "json_schema" 并提供 JSON Schema，也支持 json_object。

字段默认值为 prompt；旧目录缺少该字段时也必须按 prompt 处理。不要从旧 supportsJson 标记或模型名称推断原生 JSON 支持。该字段为兼容性新增字段，既有能力和参数字段保持原有含义。调用方仍须解析并校验结果，不能仅凭声明跳过业务 Schema 校验。

获取 Team 模型目录 ​

需要 model Scope、Team-bound Token 和目标 Team 权益：

http
GET /api/v1/open/teams/<team-id>/models
Authorization: Bearer <team-access-token>
Accept: application/json

Team 响应额外包含：

  • teamId；
  • teamContextVersion；
  • planVersionId；
  • catalogVersion；
  • items 模型列表。

客户端可以按 catalogVersion 缓存目录，但 Team、角色、会员或上下文变化后必须重新获取。

json
{
  "success": true,
  "data": {
    "teamId": "team_01",
    "teamContextVersion": 7,
    "planVersionId": "plan_version_03",
    "catalogVersion": "sha256:catalog-digest",
    "items": [
      {
        "modelCode": "othan-2.0",
        "displayName": "Othan 2.0",
        "modelType": "chat",
        "inputsText": true,
        "inputsImage": true,
        "outputsText": true,
        "structuredOutputMode": "prompt",
        "outputsImage": false,
        "parameterSchemaVersion": 1,
        "parameterSpec": {}
      }
    ]
  },
  "request_id": "req_02"
}

调用兼容 Chat Completions 的模型网关 ​

http
POST /api/proxy/v1/chat/completions
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "model": "<modelCode>",
  "messages": [
    { "role": "system", "content": "你是企业内部智能体。" },
    { "role": "user", "content": "总结这份内容。" }
  ],
  "stream": true
}

Personal OAuth Token 支持普通非流式和流式调用。Team OAuth Token 当前只能在完整工作流上下文中使用非流式调用。

Personal 非流式调用：

bash
curl 'https://claw.zhenhuiai.com/api/proxy/v1/chat/completions' \
  --header 'Authorization: Bearer <personal-access-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "othan-2.0",
    "messages": [{"role":"user","content":"用三点总结这段内容"}],
    "stream": false
  }'
json
{
  "id": "chatcmpl_01",
  "object": "chat.completion",
  "created": 1788067200,
  "model": "othan-2.0",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "1. ...\n2. ...\n3. ..." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 120, "completion_tokens": 48, "total_tokens": 168 }
}

Personal 流式调用只需改为 "stream": true，并用 SSE 逐行读取 data: 事件，直到收到 data: [DONE]。客户端必须同时处理网络中断、非 2xx JSON 错误和流内错误事件。

平台错误响应示例：

json
{
  "success": false,
  "code": "OPEN_AGENT_SCOPE_REQUIRED",
  "message": "The model scope is required",
  "request_id": "req_error_01"
}

调用 TTS 网关 ​

同一 model Scope 也可读取可用 TTS 配置和音色，并提交语音合成：

http
GET /api/proxy/v1/tts/options
Authorization: Bearer <access-token>

先读取目录，再让用户明确选择 ttsConfigId 与该配置的 voices[].voiceId。模型不固定音色，兼容字段 defaultVoiceId 为空字符串，不得用首个候选代替用户选择。音色 ID 是不透明值，可包含空格和括号。没有音色不隐藏已启用且有价格/格式的模型，保留管理/复刻入口；实际生成前仍必须选择合法音色。

目录按可信 Personal/Team 上下文隔离，只返回共用与当前账户可用音色；公开赞助只能使用共用音色。音色的 shared、state、activationPoints、expiresAt 表达来源、状态和待首次使用费用/期限。账户或 Team 切换后必须重新读取，不能把旧空间音色缓存给新空间。channelId 可用于识别同通道兼容关系，不是授权凭据。

voiceLibraryUrl 在普通账户上下文提供个人/团队音色管理入口，公开赞助为空。用户在该门户使用原有网页登录创建、改名、删除或主动付费试听，不通过 OAuth 开放接口代写音色库。新复刻音色须在显示的 7 天期限内首次正式使用；创建不扣积分且不隐式生成试听，首次合成/主动付费试听会把创建时快照的一次性复刻积分与合成费一起预留结算，成功激活后同通道其他模型不再收复刻费。执行前应展示该费用，不能把主动试听当成免费测试。

http
POST /api/proxy/v1/audio/speech
Authorization: Bearer <access-token>
X-Request-ID: <stable-request-id>
Content-Type: application/json

{
  "tts_config_id": "<ttsConfigId>",
  "voice": "<voiceId>",
  "input": "需要生成语音的文本",
  "response_format": "mp3",
  "speed": 1.0
}

input 为 1–9,999 字符且不能全为空白，格式须来自当前模型 outputFormats。可选参数还包括 volume、pitch、emotion、sample_rate、bitrate、audio_channel、language_boost、text_normalization 和 latex_read；类型、范围和枚举见完整 API 参考的 TtsSpeechInput，不要透传未声明的供应商参数。

X-Request-ID 是收费请求的必填幂等键。成功响应为所选格式的音频二进制，且 Cache-Control 固定为 no-store。调用方应读取以下响应头：

响应头含义
X-Xiaoya-Request-Id平台确认的幂等请求 ID
X-Xiaoya-Tts-Config-Id / X-Xiaoya-Voice-Id实际使用的小雅 TTS 配置与音色
X-Xiaoya-Input-Characters / X-Xiaoya-Usage-Characters输入字符数与供应商确认的结算字符数
X-Xiaoya-Actual-Usage / X-Xiaoya-Audio-Duration-Ms按价格规则计算的实际单位与音频时长
X-Xiaoya-Charged-Points本次最终总扣分，包含本次需要结算的一次性复刻费用

相同账户范围内重试必须复用同一个 X-Request-ID；结果未知时平台保留预留进入对账，调用方不得换请求 ID 自动重投。首次使用待核实时，TTS_VOICE_ACTIVATION_IN_PROGRESS 阻止其他请求再次激活音色；不能承诺已退款或诱导重新提交。成功音频由调用方保存，已结算重试返回 TTS_REQUEST_ALREADY_SETTLED 而不再次合成。公开目录不会返回供应商密钥、上游模型或内部地址。

谁承担费用？ ​

调用方式模型费用归属
智能体调用自己的供应商或网关智能体开发者
Personal OAuth Token 调用小雅网关当前用户余额
Team OAuth Token 调用小雅网关当前 Team 共享钱包，并受成员配额约束

智能体仍然承担自己的服务器、存储和业务工作流成本。只有经过小雅模型网关的模型调用才按上述用户或 Team 上下文结算。

实现建议 ​

  • 每次运行使用模型目录返回的稳定 modelCode；
  • 按 modelType 和能力字段筛选，不从展示名推断能力；
  • 参数只从 parameterSpec 构造，并处理 Schema 版本变化；
  • 不把 OAuth Token 传给浏览器或模型 Prompt；
  • 对流式网络中断保留客户端请求 ID，但不要用新幂等身份重复 Team 运行；
  • 记录安全的模型代码、状态、耗时、平台 request_id 和用量摘要，不记录完整敏感输入。

接口的完整请求字段、Header 与响应 Schema 见完整 API 参考。

OAuth credentials and model-provider secrets must remain on trusted servers.

© 2026 Xiaoya Claw