# OpenAI 协议兼容 · 图像接口

**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` 中），**不要重新提交**。





## Request Parameters

### model

- **Type:** string
- **Required:** 必选

模型 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。
### prompt

- **Type:** string
- **Required:** 必选

期望图像的文字描述。
### image

- **Type:** file | file[]
- **Required:** 条件必填

仅 edits，multipart 表单。'image' 与 'image[]' 两种 part 名都支持；每张输入图一个 part。
### images

- **Type:** object[]
- **Required:** 条件必填

仅 edits，JSON 请求体。每个元素只能二选一：image_url（公网 https URL，或 base64 data: URL，最大 10 MiB）或 file_id（POST /v3/files 返回的 Tripo file_token）。
### size

- **Type:** string
- **Required:** 可选
- **Default:** `1024x1024`

输出分辨率。传 'auto' 或不传都会解析为 1024x1024，以保证下单前积分可预知。

与原生端点规则一致：每条边必须是 16 像素的整数倍。
### quality

- **Type:** string
- **Required:** 可选
- **Default:** `low`

渲染档位。传 'auto' 或不传都表示基础档。

gpt-image-2 支持 low / medium / high；gpt-image-2.5-* 另外支持 xhigh 与 max。
### background

- **Type:** string
- **Required:** 可选

auto / opaque / transparent。仅对 gpt-image-2.5-* 生效；transparent 要求 output_format=png。
### output_format

- **Type:** string
- **Required:** 可选
- **Default:** `png`

png 或 jpeg；webp 会被拒绝。
### n

- **Type:** integer
- **Required:** 可选
- **Default:** `1`

必须为 1，每次请求出一张图；其它值返回 400。
### response_format

- **Type:** string
- **Required:** 可选
- **Default:** `url`

只支持 'url'。传 'b64_json' 会返回 400，而不是被静默降级。
### stream

- **Type:** boolean
- **Required:** 可选

不支持，必须为 false 或不传；不提供流式中间图。
### mask

- **Type:** file
- **Required:** 可选

可选的局部重绘遮罩，作用于第一张输入图。必须是带 alpha 通道的 PNG，且以文件 part 发送；完全透明的像素即为要重绘的区域。其他形式一律返回 400。

需与输入图同尺寸，且不超过 20 MiB。遮罩对模型是语义引导而非像素级裁剪，因此 prompt 应描述该区域，不要点名位于遮罩之外的对象。输入图本身上限为 10 MiB，上传与 data: URL 两种形式同此限制。

## Response Fields

### created

- **Type:** integer
- **Required:** 必选

Unix 时间戳（秒）。
### data[].url

- **Type:** string
- **Required:** 必选

生成图像的加签 CDN URL；本接口以此替代 b64_json。
### size / quality / output_format / background

- **Type:** string
- **Required:** 可选

回显实际生效的取值，可用于确认 'auto' 被解析成了什么。
### tripo.task_id

- **Type:** string
- **Required:** 必选

Tripo 扩展字段。同一 id 也会放在 X-Tripo-Task-Id 响应头中（出错时同样返回），便于用 GET /v3/tasks/{task_id} 对账。

## Request Example

### 文生图（官方 SDK）

```
from openai import OpenAI

client = OpenAI(
    api_key="<YOUR_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 <YOUR_API_KEY>' \
  -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 <YOUR_API_KEY>' \
  -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'
```


## Response Example

### 成功

```json
{
  "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"
  }
}
```

### 错误信封

```json
{
  "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"
  }
}
```

### 超过等待上限仍在生成

```json
{
  "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"
  }
}
```