HTTP Service API

services/opentransd 提供了一个可直接部署的 HTTP 服务，用来通过浏览器或 API 访问 OpenTrans 的转换能力。

服务定位

适合：

• 浏览器调试
• 团队内部协议验证
• 示例分享
• 自动化测试辅助
• 轻量转换工具服务

不建议把它直接理解为完整生产网关；如果你要做深度定制代理，通常会基于 SDK 自行封装业务服务。

默认启动

go run ./services/opentransd/cmd/opentransd

默认监听端口：

8080

通过环境变量修改端口：

PORT=9090 go run ./services/opentransd/cmd/opentransd

路由总览

方法	路径	用途
GET	/	浏览器转换页面
GET	/healthz	健康检查
GET POST	/convert	返回原始转换结果
GET POST	/api/convert	返回 JSON 包装结果

参数说明

通用参数

参数	必填	说明
kind	是	转换类型：request、response、stream
source	是	源协议：openai、responses、claude、gemini
target	是	目标协议：openai、responses、claude、gemini
pretty	否	是否格式化 JSON 输出

body 传递方式

支持三种方式：

1. POST body 直接传 JSON
2. GET 使用 body=...
3. GET 使用 body_b64=...

对于较复杂的 JSON，推荐使用 body_b64 或 POST。

GET /healthz

用于健康检查。

响应示例：

{
  "status": "ok"
}

POST /convert

返回纯转换结果，不附带包装字段。

请求示例：

curl -X POST "http://localhost:8080/convert?kind=request&source=openai&target=claude&pretty=1" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [
      {"role": "user", "content": "hello"}
    ]
  }'

响应示例：

{
  "model": "gpt-4.1-mini",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "hello"
        }
      ]
    }
  ]
}

GET /api/convert

返回带元信息的 JSON 包装：

{
  "kind": "request",
  "source": "openai",
  "target": "claude",
  "output": {},
  "share_url": "http://localhost:8080/?..."
}

请求示例：

http://localhost:8080/api/convert?kind=request&source=openai&target=claude&body=%7B%22model%22%3A%22gpt-4.1-mini%22%2C%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22content%22%3A%22hello%22%7D%5D%7D

POST /api/convert

请求体格式：

{
  "kind": "request",
  "source": "openai",
  "target": "claude",
  "body": {
    "model": "gpt-4.1-mini",
    "messages": [
      { "role": "user", "content": "hello" }
    ]
  },
  "pretty": true
}

kind 的含义

值	说明
request	请求体转换
response	非流式响应转换
stream	单个流式事件 payload 转换

注意：

• stream 面向的是事件 payload 级别
• 完整 SSE 帧转换更适合通过 ginx.ConvertStreamEventBody 接入

分享链接

服务会构建一个页面分享链接，把当前输入编码成：

• kind
• source
• target
• body_b64
• autorun

示例：

http://localhost:8080/?kind=request&source=openai&target=claude&body_b64=...&autorun=1

适合：

• 分享最小复现输入
• 团队协作排查
• 文档示例链接化

错误响应

服务通常返回 JSON 错误体：

{
  "error": "..."
}

常见状态码：

• 400 Bad Request：请求参数或输入格式错误
• 422 Unprocessable Entity：协议转换失败

生产使用建议

如果你要把 HTTP 服务放进真实环境，建议至少补上这些外围能力：

• 认证与鉴权
• 请求限流
• 访问日志
• tracing
• 超时控制
• 上游 provider 调用保护

OpenTrans 当前提供的是转换能力和调试服务，不是完整 API 网关产品。