UOUODUO AI Gateway

API

Messages

使用 Anthropic-style Messages 请求 Claude 兼容路由，支持 system、tools、thinking 与流式输出。

概述

Messages 接口使用 Anthropic-style 请求结构，适合已经使用 Claude SDK 或需要 `system`、`max_tokens`、`stop_sequences`、`thinking` 等字段的应用。

UOUODUO Gateway 通过 `/v1/messages` 提供兼容入口。请求头中建议包含 `anthropic-version`，便于客户端和上游行为保持一致。

请求

`POST https://api.example.com/v1/messages`

Headers

Header	必需	说明
Authorization	✓	`Bearer $UOUODUO_API_KEY`
Content-Type	✓	`application/json`
anthropic-version	✓	推荐 `2023-06-01`

Body 参数

参数	类型	必需	默认	说明
model	string	✓	-	Claude 兼容模型 ID
messages	array<object>	✓	-	user / assistant 消息列表
max_tokens	integer	✓	-	最大输出 token 数
system	string 或 array<object>	否	-	系统指令
temperature	number	否	-	采样温度，通常 0 到 1
top_p	number	否	-	nucleus sampling
top_k	integer	否	-	限制候选 token 数
stream	boolean	否	false	是否启用 SSE
stop_sequences	array<string>	否	-	停止序列
tools	array<object>	否	-	工具定义
tool_choice	object	否	-	指定工具选择策略
thinking	object	否	-	支持推理的模型可用
metadata	object	否	-	自定义追踪信息

示例

curl https://api.example.com/v1/messages \
  -H "Authorization: Bearer $UOUODUO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-5-sonnet-latest",
    "max_tokens": 800,
    "system": "你是一个严谨的代码审阅助手。",
    "messages": [
      { "role": "user", "content": "检查这段迁移脚本的风险。" }
    ]
  }'

响应

字段	类型	说明
id	string	message ID
type	string	`message`
role	string	通常为 `assistant`
content	array<object>	输出块，例如 `{ "type": "text", "text": "..." }`
model	string	实际执行模型
stop_reason	string	`end_turn`、`max_tokens`、`stop_sequence`、`tool_use` 等
usage	object	input/output token 统计，可能包含 cache token

{
  "id": "msg_abc",
  "type": "message",
  "role": "assistant",
  "content": [{ "type": "text", "text": "主要风险有三类..." }],
  "model": "claude-3-5-sonnet-latest",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 120,
    "output_tokens": 220,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

流式响应

设置 `"stream": true` 后，Messages 会返回语义化 SSE event。常见事件包括：

event	说明
message_start	响应开始，包含空 content 的 message
content_block_start	某个内容块开始
content_block_delta	文本或工具参数增量
content_block_stop	内容块结束
message_delta	stop reason、usage 等增量
message_stop	响应结束

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"风险"}}

event: message_stop
data: {"type":"message_stop"}

错误

HTTP	说明	处理建议
400	缺少 `max_tokens`、messages 格式错误或工具 schema 不合法	按字段表重新校验
401	key 无效	重新创建 API key
403	模型未开放给当前 key	检查 `/models` 与 `/app/keys`
429	限流或余额不足	查看 `/docs/guides/rate-limits` 和 `/docs/guides/billing`
529	上游过载时可能出现	使用重试和备用模型

注意事项

Anthropic SDK 的 `base_url` 也应设置为 `https://api.example.com/v1`。
`system` 不放进 `messages`，而是独立字段。
工具调用返回的 tool input 仍需服务端校验，不能直接信任模型输出。