Tripo3D

OpenAI 协议兼容 · 图像接口

http
Base URL: https://openapi.tripo3d.ai/v3
Endpoint: POST /openai/images/generations
全面兼容 OpenAI Images API 协议。把客户端的 base URL 指到 https://openapi.tripo3d.ai/v3/openai、换一下模型名即可接入， 其余调用代码无需改动。

端点

  • POST /v3/openai/images/generations — 文生图
  • POST /v3/openai/images/edits — 图生图（multipart 或 JSON）

与 OpenAI 的两处有意差异

  • 图片一律以加签 URL 返回，位于 data[0].url，不返回 b64_json。显式传 response_format="b64_json" 会返回 400，而不是被静默忽略。
  • 不返回 usage 字段。 我们按积分计费而非 token。消费明细请查 账户或任务查询。

模型名

模型名沿用 OpenAI 的官方写法，你代码里现有的模型字符串可以直接继续用。当前只有下面这三个版本，传其它任何值都会返回 404 model_not_found（带日期的快照名如 gpt-image-2-2026-04-21 同样不接受），错误信息里会列出这三个可用 ID。

  • gpt-image-2
  • gpt-image-2.5-flare
  • gpt-image-2.5-sunburst

计费与耗时

与文生图、图生图完全一致——同样的积分、同样的内容审核、 同样的并发限制。请求会一直阻塞到出图为止（通常 20–80 秒）。若 240 秒后仍在生成，会返回 400 且 code 为 generation_in_progress：任务并未失败、积分已扣一次，请改用 GET /v3/tasks/{task_id} 轮询 （task_id 在响应头 X-Tripo-Task-Id 与 tripo.task_id 中），不要重新提交。

请求参数

请求体

modelstring必选
模型 ID，沿用 OpenAI 官方写法。不在下列三个版本内的取值一律返回 404 model_not_found。
说明
取值：gpt-image-2、gpt-image-2.5-flare、gpt-image-2.5-sunburst，仅此三个。带日期的快照名不被接受；Tripo 的 chat_image_* ID 同样不接受，且 404 里会直接给出应改用的 ID。
promptstring必选
期望图像的文字描述。
imagefile | file[]条件必选
仅 edits，multipart 表单。'image' 与 'image[]' 两种 part 名都支持；每张输入图一个 part。
imagesobject[]条件必选
仅 edits，JSON 请求体。每个元素只能二选一：image_url（公网 https URL，或 base64 data: URL，最大 10 MiB）或 file_id（POST /v3/files 返回的 Tripo file_token）。
sizestring默认值: 1024x1024
输出分辨率。传 'auto' 或不传都会解析为 1024x1024，以保证下单前积分可预知。
说明
与原生端点规则一致：每条边必须是 16 像素的整数倍。
qualitystring默认值: low
渲染档位。传 'auto' 或不传都表示基础档。
说明
gpt-image-2 支持 low / medium / high；gpt-image-2.5-* 另外支持 xhigh 与 max。
backgroundstring
auto / opaque / transparent。仅对 gpt-image-2.5-* 生效；transparent 要求 output_format=png。
output_formatstring默认值: png
png 或 jpeg；webp 会被拒绝。
ninteger默认值: 1
必须为 1，每次请求出一张图；其它值返回 400。
response_formatstring默认值: url
只支持 'url'。传 'b64_json' 会返回 400，而不是被静默降级。
streamboolean
不支持，必须为 false 或不传；不提供流式中间图。
maskfile
可选的局部重绘遮罩，作用于第一张输入图。必须是带 alpha 通道的 PNG，且以文件 part 发送；完全透明的像素即为要重绘的区域。其他形式一律返回 400。
说明
需与输入图同尺寸，且不超过 20 MiB。遮罩对模型是语义引导而非像素级裁剪，因此 prompt 应描述该区域，不要点名位于遮罩之外的对象。输入图本身上限为 10 MiB，上传与 data: URL 两种形式同此限制。

返回参数

createdinteger必选
Unix 时间戳（秒）。
data[].urlstring必选
生成图像的加签 CDN URL；本接口以此替代 b64_json。
size / quality / output_format / backgroundstring
回显实际生效的取值，可用于确认 'auto' 被解析成了什么。
tripo.task_idstring必选
Tripo 扩展字段。同一 id 也会放在 X-Tripo-Task-Id 响应头中（出错时同样返回），便于用 GET /v3/tasks/{task_id} 对账。

示例

文生图（官方 SDK）
from openai import OpenAI

client = OpenAI(
    api_key="",
    base_url="https://openapi.tripo3d.ai/v3/openai",
)

result = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="a cute baby sea otter on a rock",
    n=1,
    size="auto",
    quality="auto",
)

print(result.data[0].url)
图生图（官方 SDK）
result = client.images.edit(
    model="gpt-image-2.5-flare",
    prompt="replace the background with pure white",
    image=open("input.png", "rb"),
    size="1024x1024",
)

print(result.data[0].url)
图生图（JSON 请求体）
curl -X POST 'https://openapi.tripo3d.ai/v3/openai/images/edits' \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "replace the background with pure white",
    "images": [{ "image_url": "https://example.com/input.png" }],
    "size": "1024x1024"
  }'
图生图（multipart，多张图）
curl -X POST 'https://openapi.tripo3d.ai/v3/openai/images/edits' \
  -H 'Authorization: Bearer ' \
  -F 'model=gpt-image-2.5-flare' \
  -F 'prompt=combine both objects into one product photo' \
  -F 'image[]=@a.png;type=image/png' \
  -F 'image[]=@b.png;type=image/png' \
  -F 'size=1024x1024'
成功
{
  "created": 1789598400,
  "data": [
    {
      "url": "https://cdn.tripo3d.com/.../generated_image.png?..."}
  ],
  "size": "1024x1024",
  "quality": "low",
  "output_format": "png",
  "tripo": {
    "task_id": "2f67cafc-c1aa-492f-85e8-93ec95fc6fd8"}
}
错误信封
{
  "error": {
    "message": "model 'chat_image_2' is not supported here; use 'gpt-image-2' instead",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"}
}
超过等待上限仍在生成
{
  "error": {
    "message": "the image is still being generated after 240s; it has not failed and you have been charged once — poll GET /v3/tasks/2f67cafc-... for the result instead of resubmitting",
    "type": "invalid_request_error",
    "code": "generation_in_progress"}
}