Trinity
Trinity AI

中文

English

中文

English

创建 Messages ​

面向 Anthropic Messages 协议的生文调用。请求体按 Anthropic Messages 格式透传，响应返回 Anthropic Messages 形态 JSON。

模型 ID 见 获取模型 或 模型广场。同一模型不一定支持本路径，也可使用 创建对话补全。

Endpoint ​

MethodURL
POST{TRINITY_BASE_URL}/messages

Base URL ​

项值
Base URLhttps://api.trinitydesk.ai/v1
协议HTTPS
bash
export TRINITY_BASE_URL="https://api.trinitydesk.ai/v1"
export TRINITY_API_KEY="xh-..."

Headers ​

Header必填说明
Authorization是Bearer <TRINITY_API_KEY>
Content-Type是application/json
Accept流式时text/event-stream

请求体字段 ​

字段类型必填说明
modelstring是网关模型 ID
messagesarray是消息数组，每项至少为 { role, content }
max_tokensinteger是回复最大 token 数
streamboolean / string否默认 false；true 或 "true" 时返回 SSE 流
systemstring / array否系统提示词，可为字符串或 { type, text } 数组
temperaturenumber否采样温度，0~1
top_pnumber否核采样概率阈值
top_kinteger否仅保留概率最高的 k 个 token
stop_sequencesstring[]否自定义停止序列
metadataobject否用户侧元数据（如 user_id）
toolsarray否工具定义数组
tool_choiceobject / string否工具调用策略

messages 内容格式 ​

每条消息的 content 可以是字符串或内容块数组：

字符串：

json
{ "role": "user", "content": "你好" }

内容块数组：

json
{
  "role": "user",
  "content": [
    { "type": "text", "text": "描述这张图片" },
    {
      "type": "image",
      "source": {
        "type": "base64",
        "media_type": "image/png",
        "data": "<base64>"
      }
    }
  ]
}

role 支持 user、assistant。若需预填 assistant 回复，使用 role: "assistant" 的消息。

stream 字段 ​

同时接受布尔值和字符串：

json
{ "stream": true }
json
{ "stream": "true" }

两者均启用 SSE 流式输出。

请求示例 ​

基础非流式 ​

bash
curl -sS "${TRINITY_BASE_URL}/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TRINITY_API_KEY}" \
  -d '{
    "model": "gpt-5.5",
    "max_tokens": 256,
    "messages": [
      { "role": "user", "content": "用一句话介绍你自己" }
    ]
  }'

带 System Prompt ​

bash
curl -sS "${TRINITY_BASE_URL}/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TRINITY_API_KEY}" \
  -d '{
    "model": "gpt-5.5",
    "max_tokens": 256,
    "system": "你是一个有帮助的助手",
    "messages": [
      { "role": "user", "content": "你好" }
    ]
  }'

图片输入（内容块数组） ​

bash
curl -sS "${TRINITY_BASE_URL}/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TRINITY_API_KEY}" \
  -d '{
    "model": "gpt-5.5",
    "max_tokens": 256,
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "请用一句话描述这张图片的内容" },
          {
            "type": "image",
            "source": {
              "type": "base64",
              "media_type": "image/png",
              "data": "iVBORw0K...base64数据..."
            }
          }
        ]
      }
    ]
  }'

流式 ​

bash
curl -sS -N "${TRINITY_BASE_URL}/messages" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "Authorization: Bearer ${TRINITY_API_KEY}" \
  -d '{
    "model": "gpt-5.5",
    "max_tokens": 256,
    "stream": true,
    "messages": [
      { "role": "user", "content": "你好" }
    ]
  }'

返回示例 ​

非流式响应 ​

成功时返回 Anthropic Messages 形态 JSON：

json
{
  "id": "msg_01AbCdEfGhIjKlMnOpQrStUv",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "你好！我是 Trinity AI 助手，很高兴为你服务。"
    }
  ],
  "model": "gpt-5.5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 8,
    "output_tokens": 15
  }
}
字段类型说明
idstring本次回复唯一 ID
typestring固定 "message"
rolestring固定 "assistant"
contentarray回复内容块数组，每项含 type + 对应内容
modelstring实际使用的模型 ID
stop_reasonstring停止原因：end_turn、max_tokens、stop_sequence、tool_use
stop_sequencestring | null若因 stop_sequences 停止，返回匹配序列
usageobjecttoken 用量，含 input_tokens、output_tokens

流式 SSE 事件 ​

流式输出为 text/event-stream，常见事件类型：

event含义
message_start消息开始，含 message 对象（含 id、model、usage 初始值）
content_block_start内容块开始，含 index、content_block（含 type）
content_block_delta内容块增量，含 index、delta（含 type + text）
content_block_stop内容块结束，含 index
message_delta消息级增量，含 stop_reason、stop_sequence、usage 最终值
message_stop消息结束

错误码 ​

HTTP 状态码code说明
400invalid_request_error请求体格式错误（如非法 JSON）
400model_not_supported_on_interface模型不支持本路径
401authentication_errorAPI Key 缺失或无效
402insufficient_balance余额不足
404model_not_found模型未找到
429rate_limit_exceeded速率限制
500api_error网关 / 上游服务异常

流式中途错误通过 SSE error event 返回（格式为 Anthropic error event，含 error.type 和 error.message），常见如上游超时、上游 HTTP 异常。

Python 示例 ​

python
import os
import requests

url = f"{os.environ['TRINITY_BASE_URL']}/messages"
r = requests.post(
    url,
    headers={
        "Authorization": f"Bearer {os.environ['TRINITY_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-5.5",
        "max_tokens": 256,
        "messages": [{"role": "user", "content": "用一句话介绍你自己"}],
    },
    timeout=120,
)
r.raise_for_status()
print(r.json())

相关 ​

© Trinity AI

© Trinity AI