# OpenAI-Compatible Images API
**Base URL:** `https://openapi.tripo3d.ai/v3`
**Endpoint:** `POST /openai/images/generations`
**Fully compatible with the OpenAI Images API protocol.** Point your existing client at `https://openapi.tripo3d.ai/v3/openai`, change the model name, and keep the rest of your integration unchanged.Endpoints
- `POST /v3/openai/images/generations` — text to image
- `POST /v3/openai/images/edits` — image to image (multipart or JSON)
Two deliberate differences from OpenAI
- **The image is always returned as a signed URL** in `data[0].url`, never as `b64_json`. Passing `response_format="b64_json"` returns 400 rather than being silently ignored.
- **No `usage` block.** Billing is in credits, not tokens. Use Account or Task Query for spend.
Model namesModel ids use OpenAI's own spelling, so the string already in your code keeps working. These three are the only versions that exist — anything else, dated snapshot ids included, returns 404 `model_not_found` listing the three supported ids.
- `gpt-image-2`
- `gpt-image-2.5-flare`
- `gpt-image-2.5-sunburst`
Billing and timingIdentical to Text to Image and Image to Image — same credits, same content moderation, same concurrency limits. The request blocks until the image is ready (typically 20–80s). If it is still running after 240s you get a 400 with code `generation_in_progress`: the task has not failed and was charged once, so poll `GET /v3/tasks/{task_id}` (the id is in `X-Tripo-Task-Id` and in `tripo.task_id`) instead of resubmitting.
## Request Parameters
### model
- **Type:** string
- **Required:** Required
Model id, in OpenAI's spelling. Anything outside the three listed versions is rejected with 404 model_not_found.
One of: gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst — these three only. Dated snapshot ids are not accepted, nor are the Tripo chat_image_* ids.
### prompt
- **Type:** string
- **Required:** Required
Text description of the desired image.
### image
- **Type:** file | file[]
- **Required:** Conditional
Edits only, multipart form. Both 'image' and 'image[]' part names are accepted; send one part per input image.
### images
- **Type:** object[]
- **Required:** Conditional
Edits only, JSON body. Each entry sets exactly one of image_url (public https URL, or base64 data: URL up to 10 MiB) or file_id (a Tripo file_token from POST /v3/files).
### size
- **Type:** string
- **Required:** Optional
- **Default:** `1024x1024`
Output resolution. 'auto' and an omitted value both resolve to 1024x1024 so the credit cost is known before the request runs.
Same rules as the native endpoints: each edge must be a multiple of 16px.
### quality
- **Type:** string
- **Required:** Optional
- **Default:** `low`
Rendering tier. 'auto' and an omitted value both mean the base tier.
gpt-image-2: low, medium, high. gpt-image-2.5-*: additionally xhigh and max.
### background
- **Type:** string
- **Required:** Optional
auto, opaque or transparent. Only effective on gpt-image-2.5-*; transparent requires output_format=png.
### output_format
- **Type:** string
- **Required:** Optional
- **Default:** `png`
png or jpeg. webp is rejected.
### n
- **Type:** integer
- **Required:** Optional
- **Default:** `1`
Must be 1 — one image per request. Any other value returns 400.
### response_format
- **Type:** string
- **Required:** Optional
- **Default:** `url`
Only 'url' is supported. 'b64_json' returns 400 rather than being silently downgraded.
### stream
- **Type:** boolean
- **Required:** Optional
Not supported; must be false or omitted. Partial images are not available.
### mask
- **Type:** file
- **Required:** Optional
Optional inpainting mask, applied to the first input image. Must be a PNG with an alpha channel, sent as a file part; its fully transparent pixels mark the region to redraw. Anything else returns 400.
Same dimensions as the input image, and at most 20 MiB. The mask guides the model semantically rather than clipping pixels, so word the prompt to describe the region rather than an object that sits outside it. The input image itself is capped at 10 MiB, whether it is uploaded or sent as a data: URL.
## Response Fields
### created
- **Type:** integer
- **Required:** Required
Unix timestamp in seconds.
### data[].url
- **Type:** string
- **Required:** Required
Signed CDN URL of the generated image. This replaces b64_json.
### size / quality / output_format / background
- **Type:** string
- **Required:** Optional
Echo of what was actually applied — useful to confirm how 'auto' was resolved.
### tripo.task_id
- **Type:** string
- **Required:** Required
Tripo extension. The same id is returned in the X-Tripo-Task-Id response header, including on errors, so a task can always be reconciled with GET /v3/tasks/{task_id}.
## Request Example
### Text to image (official 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)
```
### Image to image (official 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)
```
### Image to image (JSON body)
```
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"
}'
```
### Image to image (multipart, two images)
```
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
### Success
```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"
}
}
```
### Error envelope
```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"
}
}
```
### Still generating after the wait limit
```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"
}
}
```
http
Base URL: https://openapi.tripo3d.ai/v3
Endpoint:POST /openai/images/generations
Fully compatible with the OpenAI Images API protocol. Point your existing client at https://openapi.tripo3d.ai/v3/openai, change the model name, and keep the rest of your integration unchanged.
Endpoints
POST /v3/openai/images/generations — text to image
POST /v3/openai/images/edits — image to image (multipart or JSON)
Two deliberate differences from OpenAI
The image is always returned as a signed URL in data[0].url, never as b64_json. Passing response_format="b64_json" returns 400 rather than being silently ignored.
No usage block. Billing is in credits, not tokens. Use Account or Task Query for spend.
Model names
Model ids use OpenAI's own spelling, so the string already in your code keeps working. These three are the only versions that exist — anything else, dated snapshot ids included, returns 404 model_not_found listing the three supported ids.
gpt-image-2
gpt-image-2.5-flare
gpt-image-2.5-sunburst
Billing and timing
Identical to Text to Image and Image to Image — same credits, same content moderation, same concurrency limits. The request blocks until the image is ready (typically 20–80s). If it is still running after 240s you get a 400 with code generation_in_progress: the task has not failed and was charged once, so poll GET /v3/tasks/{task_id} (the id is in X-Tripo-Task-Id and in tripo.task_id) instead of resubmitting.
Request Parameters
Request Body
modelstringRequired
Model id, in OpenAI's spelling. Anything outside the three listed versions is rejected with 404 model_not_found.
Notes
One of: gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst — these three only. Dated snapshot ids are not accepted, nor are the Tripo chat_image_* ids.
promptstringRequired
Text description of the desired image.
imagefile | file[]Conditional
Edits only, multipart form. Both 'image' and 'image[]' part names are accepted; send one part per input image.
imagesobject[]Conditional
Edits only, JSON body. Each entry sets exactly one of image_url (public https URL, or base64 data: URL up to 10 MiB) or file_id (a Tripo file_token from POST /v3/files).
sizestringdefault: 1024x1024
Output resolution. 'auto' and an omitted value both resolve to 1024x1024 so the credit cost is known before the request runs.
Notes
Same rules as the native endpoints: each edge must be a multiple of 16px.
qualitystringdefault: low
Rendering tier. 'auto' and an omitted value both mean the base tier.
Notes
gpt-image-2: low, medium, high. gpt-image-2.5-*: additionally xhigh and max.
backgroundstring
auto, opaque or transparent. Only effective on gpt-image-2.5-*; transparent requires output_format=png.
output_formatstringdefault: png
png or jpeg. webp is rejected.
nintegerdefault: 1
Must be 1 — one image per request. Any other value returns 400.
response_formatstringdefault: url
Only 'url' is supported. 'b64_json' returns 400 rather than being silently downgraded.
streamboolean
Not supported; must be false or omitted. Partial images are not available.
maskfile
Optional inpainting mask, applied to the first input image. Must be a PNG with an alpha channel, sent as a file part; its fully transparent pixels mark the region to redraw. Anything else returns 400.
Notes
Same dimensions as the input image, and at most 20 MiB. The mask guides the model semantically rather than clipping pixels, so word the prompt to describe the region rather than an object that sits outside it. The input image itself is capped at 10 MiB, whether it is uploaded or sent as a data: URL.
Response
createdintegerRequired
Unix timestamp in seconds.
data[].urlstringRequired
Signed CDN URL of the generated image. This replaces b64_json.
size / quality / output_format / backgroundstring
Echo of what was actually applied — useful to confirm how 'auto' was resolved.
tripo.task_idstringRequired
Tripo extension. The same id is returned in the X-Tripo-Task-Id response header, including on errors, so a task can always be reconciled with GET /v3/tasks/{task_id}.
Examples
Text to image (official 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)
Image to image (official 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)
{
"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"}
}
Still generating after the wait limit
{
"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"}
}
