API 概述
通过 HTTPS + API Key 调用生文、生图、生视频。在请求体中用 model 指定模型 ID，网关完成鉴权与路由。
基址
| 项 | 值 |
|---|---|
| Base URL | https://api.trinitydesk.ai/v1 |
| 协议 | HTTPS |
除 Gemini 原生接口外，路径均相对于含 /v1 的 base（示例：POST {TRINITY_BASE_URL}/chat/completions）。Gemini generateContent 使用 API Host https://api.trinitydesk.ai 与 /v1beta/... 路径，见 创建 Gemini Content。
鉴权
每个请求须携带：
Authorization: Bearer <TRINITY_API_KEY>
Content-Type: application/json追踪与结算（请求头）
适用于生文类 POST（含流式、含 Gemini Content）及生图 POST /chat/completions、POST /images/generations、POST /images/edits。
| 请求头 | 必填 | 作用 |
|---|---|---|
X-Request-Id | 否 | 追踪 ID，排障与日志关联；最长 128 字符；未传时服务端生成 |
X-Idempotency-Key | 否 | 结算幂等键；同 workspace 内相同键仅首笔成功扣费；重试须保持不变 |
X-Conversation-Id | 否 | 会话分组 ID；多轮对话建议固定传同一值；最长 128 字符 |
X-Session-Id | 否 | X-Conversation-Id 别名；仅当未传后者时生效 |
响应（含 SSE）回写：X-Request-Id、X-Settlement-Key；传入 X-Conversation-Id 时回写该头。
计费
不传 X-Idempotency-Key 时，每次 HTTP 调用独立计费。网络超时后重放同一笔业务，应固定结算键，追踪 ID 可更换。
能力一览
| 能力 | 方法 | 路径 |
|---|---|---|
| 获取模型 | GET | /models |
| 对话补全（生文） | POST | /chat/completions |
| Responses（生文） | POST | /responses |
| Messages（生文） | POST | /messages |
| Gemini Content（生文） | POST | /v1beta/models/{model}:generateContent · :streamGenerateContent |
| 图像生成（Images） | POST | /images/generations |
| 图像编辑（Images） | POST | /images/edits |
| 图像生成（统一契约） | POST | /chat/completions + modalities / image_config |
| 查询生图任务 | GET | /image/tasks/{taskId} |
| 创建视频任务 | POST | /video/generations |
| 查询视频任务 | GET | /video/tasks/{taskId} |
| 登记视频素材 | POST | /video/assets |
| 查询视频素材 | GET | /video/assets/{assetId} |
| 实时音频 client_secrets | POST | /realtime/client_secrets |
| 实时音频 WebRTC | POST | /realtime/calls |
| 实时音频 WebSocket | Upgrade | /realtime?model= |
| 路径 | 适用场景 |
|---|---|
/chat/completions | 文本、工具、多模态输入；生图统一契约（modalities / image_config） |
/images/generations | OpenAI / Azure Images 文生图形态 |
/images/edits | OpenAI / Azure Images 改图形态（multipart） |
/responses | 客户端按 Responses 协议组装请求 |
/messages | 客户端按 Anthropic Messages 协议组装请求 |
/v1beta/models/{model}:generateContent | 客户端按 Gemini generateContent 协议组装请求 |
同一模型不一定支持全部路径。可用模型 ID 见 GET /models 或 模型广场。
生图有两条路径：Images 兼容见 创建图像（Images）、编辑图像（Images）；统一契约见 创建图像生成（chat）。
模型 ID
请求体 model（或 Gemini Content 路径参数 {model}）填模型 ID（非展示名）。示例：
| 模态 | 示例 ID |
|---|---|
| 生文 | gpt-5.5、claude-sonnet-4-6、gemini-2.5-flash |
| 生图 | gpt-image-2、gemini-2.5-flash-image、Hunyuan-3.0、OG-image2-medium |
| 生视频 | kling-2.6 |
查询方式：GET /models（可选 ?modality=text|image|video|all）或 模型广场。
价目与折扣
公开价目见模型列表与广场展示。企业折扣、专属价目请联系我们（控制台工单或您的客户成功经理）。
响应与错误
- 成功：JSON，或
stream: true时的 SSE（text/event-stream）。 - 失败：
error对象，含message、type、code— 见 错误与调试。