▶ GET /health GET

健康检查，返回版本与上游状态。


    
{"status":"ok","version":"1.2.0","upstream":"configured"}

  






  
▶ POST /v1/messages POST

  

    
非流式 Claude Messages API 调用。

    
content[].index 按 block 顺序从 0 递增：text(0)，tool_use(1,2,...)

    

    
content 含 {"type":"text","text":"...","index":0}，stop_reason="end_turn"

  






  
▶ POST /v1/messages (stream) STREAM

  

    
流式 SSE 事件序列。

    
content_block_start 声明新 block(index 递增) → content_block_delta 携带内容 → content_block_stop 关闭 block。三者 index 必须一致。

    

    
message_start → content_block_start(0) → delta(0)* → stop(0) → message_delta → message_stop

  






  
▶ POST /v1/messages (tools) TOOLS

  

    
携带 tools 参数触发工具调用。

    
非 stream：content[0]=text(index:0) + content[1]=tool_use(index:1)
stream：每个 block 的 start/delta/stop index 一致且递增

    

    
text(index:0) + tool_use(index:1)，stop_reason="tool_use"

  






  
▶ POST /v1/messages (tools + stream) TOOLS STREAM

  

    
流式工具调用——验证 input_json_delta 和 index 递增。

    
上游多个顺序 tool_call（每个 tc.index=0），cf-proxy 为每个新 tc.id 分配递增 toolBlockIndex：新 tool_call 前先发 content_block_stop 关闭前一个 block。

    

    
start(0,tool_use) → delta(0)* → stop(0) → start(1,tool_use) → delta(1)* → stop(1) → message_delta(tool_use)

  






  
▶ POST /v1/messages (tool_result) TOOLS

  

    
将工具结果回传 AI，完成多轮调用。tool_use_id 必须与 AI 返回的 id 匹配。

    
tool_use.id 与 tool_result.tool_use_id 必须匹配。cf-proxy 转换为 OpenAI 的 tool_calls + role:tool

    

  






  
▶ POST /v1/responses POST

  

    
Codex CLI Responses API，直接透传不做协议转换。上游需支持 Responses API。

    

  






  
▶ 查询参数 ?upstream= ?model=

  

    
URL 参数动态覆盖上游和模型，无需修改环境变量。

    
?upstream= 智能拼接（不产生 /v1/v1/）：https://x.com → +/v1/chat/completions
https://x.com/v1 → +/chat/completions
https://x.com/v1/chat/completions → 直接使用
?model= 覆盖请求体中的 model 字段

    

  






  
▶ 错误码 ERROR

  

    
各类错误输入返回 Claude 格式错误响应。

    

  






  
▶ 多轮对话 TOOLS STREAM

  

    
提问→工具调用→结果→最终回复，每轮 content index 独立从 0 开始。

    
Round 1：user → assistant [text(0), tool_use(1)] → stop_reason="tool_use"
Round 2：user [tool_result(0)] → assistant [text(0)] → stop_reason="end_turn"