Trinity
Trinity AI

中文

English

中文

English

创建图像生成（chat） ​

向生图模型发送提示词并生成图片。使用统一契约：POST /chat/completions，通过 modalities 声明图片输出，并用 image_config 控制画幅、格式、参考图等。

OpenAI Images 形态（prompt / size / n，响应为 created + data[]）见 创建图像（Images）、编辑图像（Images）。

模型 ID 见 获取模型（modality=image）或 模型广场。

Endpoint ​

MethodURL说明
POST{TRINITY_BASE_URL}/chat/completions创建生图任务，同步等待
GET{TRINITY_BASE_URL}/image/tasks/{taskId}查询任务进度/结果

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

请求示例 ​

基础生图 ​

bash
curl -sS "${TRINITY_BASE_URL}/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TRINITY_API_KEY}" \
  -d '{
    "model": "Hunyuan-3.0",
    "messages": [{ "role": "user", "content": "赛博朋克风格未来城市夜景" }],
    "modalities": ["image", "text"]
  }'

带参考图 ​

bash
curl -sS "${TRINITY_BASE_URL}/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TRINITY_API_KEY}" \
  -d '{
    "model": "GG-2.5",
    "messages": [{ "role": "user", "content": "赛博朋克城市夜景，霓虹倒影，电影光效" }],
    "modalities": ["image", "text"],
    "image_config": {
      "image_size": "1K",
      "aspect_ratio": "16:9",
      "output_format": "url",
      "output_image_format": "png",
      "reference_images": [
        {
          "type": "url",
          "url": "https://example.com/ref-building.png",
          "text": "保留主建筑轮廓"
        }
      ]
    }
  }'

查询任务 ​

创建生图同步超时（默认 300s）后，可用返回的任务 ID 继续查询：

bash
curl -sS "${TRINITY_BASE_URL}/image/tasks/imgtsk_xxx" \
  -H "Authorization: Bearer ${TRINITY_API_KEY}"

请求体字段 ​

字段类型必填说明
modelstring是生图模型 ID
messagesarray是提示词与可选参考图；至少 1 条
messages[].contentstring | array是string：纯文本 prompt；array：可含 text / image_url Part
modalitiesarray建议须含 image；可含 text
streamboolean否必须为 false 或省略；true 会报错
image_configobject否分辨率、宽高比、输出格式、参考图等（见下方）
model_specific_configobject否供应商专有参数，如 negative_prompt、seed

image_config 和 model_specific_config 的完整字段见 图像生成 · 高级参数。

返回字段 ​

字段类型说明
idstring完成 ID，形如 chatcmpl-imgtsk_xxx
objectstring固定 "chat.completion"
modelstring模型 ID
choices[].message.rolestring固定 "assistant"
choices[].message.contentstring文本描述（若 modalities 含 text）
choices[].message.imagesarray生成图片列表，每项 { type, image_url: { url } }
choices[].finish_reasonstring固定 "stop"
trinity_task.task_idstring任务 ID，形如 imgtsk_xxx
trinity_task.modestring固定 "sync"
trinity_task.statusstring任务状态："succeeded" / "failed" / "running"
usage.image_countinteger实际生成图片张数

返回示例 ​

创建生图成功 ​

json
{
  "id": "chatcmpl-imgtsk_abc123",
  "object": "chat.completion",
  "model": "GG-2.5",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "这是一张赛博朋克风格的城市夜景图...",
        "images": [
          {
            "type": "image_url",
            "image_url": { "url": "https://..." }
          }
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0,
    "image_count": 1
  },
  "trinity_task": {
    "task_id": "imgtsk_xxx",
    "mode": "sync",
    "status": "succeeded"
  }
}

任务查询 ​

json
{
  "task_id": "imgtsk_xxx",
  "mode": "sync",
  "status": "succeeded",
  "model": "GG-2.5",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "",
        "images": [
          {
            "type": "image_url",
            "image_url": { "url": "https://..." }
          }
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "image_count": 1
  }
}

错误码 ​

HTTP 状态码code说明
400invalid_request请求体格式错误，或 stream: true
400model_not_supported_on_interface模型不支持生图接口
401authentication_errorAPI Key 缺失或无效
402insufficient_balance余额不足
404model_not_found模型未找到
408generation_timeout生图超时（默认 300s），可用 task_id 继续查询
429rate_limit_exceeded速率限制

完整错误码见 错误与调试。

Python 示例 ​

python
import os
import requests

r = requests.post(
    f"{os.environ['TRINITY_BASE_URL']}/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['TRINITY_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "Hunyuan-3.0",
        "messages": [{"role": "user", "content": "赛博朋克风格未来城市夜景"}],
        "modalities": ["image", "text"],
    },
    timeout=300,
)
r.raise_for_status()
resp = r.json()
task_id = resp.get("trinity_task", {}).get("task_id")
images = resp.get("choices", [{}])[0].get("message", {}).get("images", [])
for img in images:
    print(img.get("image_url", {}).get("url"))

相关 ​

© Trinity AI

© Trinity AI