模型网关 API

第一版模型网关提供最小可测的模型中转能力：模型列表、文本模型调用、音频转文本。

当前 Base URL：

/api/model-gateway/v1

后续接入动态子域名后，再扩展为独立 Inference API / Audio API 域名。

端点索引

GET /api/model-gateway/v1/models

返回当前 API Key 可用的 OpenAI-compatible 模型列表。

POST /api/model-gateway/v1/chat/completions

执行文本或多模态 Chat Completions。支持普通 JSON 响应与流式 SSE，消费归因到调用方 Team。

POST /api/model-gateway/v1/audio/transcriptions

使用 multipart/form-data 上传 file 并指定 model，返回 OpenAI-compatible 音频转写结果。

Authentication

公开 API 调用使用现有团队 API Key。支持两种认证方式：

# X-API-Key header
curl -H "X-API-Key: YOUR_KEY" /api/model-gateway/v1/models

# Bearer Token
curl -H "Authorization: Bearer YOUR_KEY" /api/model-gateway/v1/models

API Key、团队余额、API Key 限额和扣费均复用现有体系。

官方移动端可以使用 OAuth access token 调用同一组端点：

curl -H "Authorization: Bearer wno-ACCESS_TOKEN" \
  /api/model-gateway/v1/models

移动端 OAuth token 必须具备 mobile:full scope。后端会把该用户映射到个人默认 project/team，并创建或复用一个隐藏的 Mobile App API Key 作为账单锚点。这个系统 API Key 不会返回给客户端，也不会在用户 API Key 管理界面展示或允许删除。

普通 Supabase JWT 不属于模型网关用户态认证范围；未授权 OAuth app、匿名请求和 scope 不足的 token 会被拒绝。

Endpoints

Endpoint	Description
GET /models	List available text and ASR models
POST /chat/completions	OpenAI-compatible chat completion, supports streaming
POST /audio/transcriptions	OpenAI-compatible audio transcription

Models

curl -H "Authorization: Bearer YOUR_KEY" \
  /api/model-gateway/v1/models

响应：

{
  "object": "list",
  "data": [
    {
      "id": "qwen3:32b",
      "object": "model",
      "created": 0,
      "owned_by": "WaiNao",
      "capabilities": ["text"],
      "billing": { "unit": "token" }
    },
    {
      "id": "sense-voice-small",
      "object": "model",
      "created": 0,
      "owned_by": "WaiNao",
      "capabilities": ["asr"],
      "billing": { "unit": "second" }
    }
  ]
}

仅返回已发布、已上架、已配置计费且有可用供应链的文本模型和 ASR 模型。

Chat Completions

curl -X POST /api/model-gateway/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3:32b",
    "messages": [{"role": "user", "content": "帮我润色这段文字"}],
    "stream": false
  }'

流式调用：

curl -X POST /api/model-gateway/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3:32b",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

第一版支持常用字段：

Field	Type	Required	Notes
model	string	yes	/models 返回的模型 ID
messages	array	yes	OpenAI Chat messages
stream	boolean	no	true 时返回 SSE
temperature	number	no	透传到内部 AI service
max_tokens	number	no	映射为内部 maxOutputTokens
stop	string or string[]	no	停止词

计费：按现有文本模型 token 价格记录 model_usage。

Audio Transcriptions

curl -X POST /api/model-gateway/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "file=@sample.wav" \
  -F "model=sense-voice-small" \
  -F "language=auto" \
  -F "response_format=json"

响应：

{ "text": "转写结果" }

第一版约束：

• model 必填，必须是 /models 返回的 capabilities 含 asr 的模型。
• response_format 仅支持 json。
• 服务端必须能解析音频时长，无法确定时长时返回 422。
• 文件大小上限为 25 MiB。

计费：按 ASR 模型 billing_rules.billing_unit = second 的秒级价格记录 model_usage。

Errors

错误响应使用 OpenAI-compatible 结构：

{
  "error": {
    "message": "Missing API key or authorization header",
    "type": "authentication_error",
    "code": "missing_api_key"
  }
}

常见状态：

Status	Code	Description
401	missing_api_key / invalid_api_key	API Key 缺失或无效
402	insufficient_quota	团队余额不足
403	api_key_credit_limit_exceeded / insufficient_scope	API Key 限额已用尽，或 OAuth scope 不允许访问模型网关
404	model_not_found	模型不存在或不可用于该接口
422	audio_duration_unavailable	无法确定音频时长，拒绝执行以避免错误计费
502	model_upstream_error / asr_upstream_failed	上游模型供应链失败