curl -X POST "https://mvp.tryunsora.com/api/v1/image-generations/create" \
-H "Authorization: Bearer uns_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Product photo on marble, soft studio light",
"model": "nano-banana-2",
"aspectRatio": "1:1",
"resolution": "2k"
}'
curl -X POST "https://mvp.tryunsora.com/api/v1/image-generations/create" \
-H "Authorization: Bearer uns_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Same character, new outfit, editorial look",
"model": "gpt-image-2",
"aspectRatio": "9:16",
"resolution": "2k",
"referenceImages": [
"https://cdn.example.com/ref-1.jpg"
]
}'
{
"success": true,
"generation": {
"id": "<string>",
"status": "<string>",
"model": "<string>",
"mode": "<string>",
"modelId": "<string>"
},
"model": "<string>",
"creditsDeducted": 123,
"creditsRemaining": 123
}{
"error": "<string>",
"success": true,
"code": "<string>",
"message": "<string>"
}Image generator
Create image
Queue an AI image generation job from a text prompt with models like GPT Image and Seedream, then poll until your images are ready.
POST
/
image-generations
/
create
curl -X POST "https://mvp.tryunsora.com/api/v1/image-generations/create" \
-H "Authorization: Bearer uns_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Product photo on marble, soft studio light",
"model": "nano-banana-2",
"aspectRatio": "1:1",
"resolution": "2k"
}'
curl -X POST "https://mvp.tryunsora.com/api/v1/image-generations/create" \
-H "Authorization: Bearer uns_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Same character, new outfit, editorial look",
"model": "gpt-image-2",
"aspectRatio": "9:16",
"resolution": "2k",
"referenceImages": [
"https://cdn.example.com/ref-1.jpg"
]
}'
{
"success": true,
"generation": {
"id": "<string>",
"status": "<string>",
"model": "<string>",
"mode": "<string>",
"modelId": "<string>"
},
"model": "<string>",
"creditsDeducted": 123,
"creditsRemaining": 123
}{
"error": "<string>",
"success": true,
"code": "<string>",
"message": "<string>"
}Creates an image generation job. Credits are deducted when the job is queued. Poll Poll generation status with the returned
generation.id until status is COMPLETED or FAILED.
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer uns_* API key or Clerk JWT |
Idempotency-Key | No | Max 128 chars. Replays the same response for 24h on API key requests |
Content-Type | Yes | application/json |
Request body
string
required
Text prompt for the image.
string
Model key. Default:
nano-banana-2.model | Display name | resolution values | aspectRatio |
|---|---|---|---|
nano-banana-2 | Google Nano Banana 2 | 1k, 2k, 4k | auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 4:5, 5:4, 21:9, 1:4, 4:1, 1:8, 8:1 |
nano-banana-pro | Google Nano Banana Pro | 1k, 2k, 4k | 1:1, 2:3, 3:4, 4:5, 3:2, 4:3, 5:4, 16:9, 21:9 |
seedream-v5-lite | ByteDance Seedream v5.0 Lite | basic, high (quality) | 1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9 |
gpt-image-1.5 | OpenAI GPT-Image 1.5 | 1024x1024, 1024x1536, 1536x1024 (use as resolution) | — |
gpt-image-2 | OpenAI GPT Image 2 | 1k, 2k, 4k | auto, 1:1, 9:16, 16:9, 4:3, 3:4 |
string
Aspect ratio. Must be allowed for the chosen
model. Default: auto (where supported).string
Output size or quality tier. Must match the chosen
model (see table above). Default: 2k for most models.string[]
Reference image URLs (public HTTPS). Use for style or subject guidance. Max count depends on model (up to 14–16).
boolean
Enable NSFW filtering when supported by the provider pipeline.
Async completion
Poll Poll generation status withgeneration.id until status is COMPLETED or FAILED. Webhooks are not supported on the public API.
Response
{
"success": true,
"generation": {
"id": "cm123abc",
"status": "QUEUED"
},
"creditsDeducted": 5,
"creditsRemaining": 95
}
Example
curl -X POST "https://mvp.tryunsora.com/api/v1/image-generations/create" \
-H "Authorization: Bearer uns_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Product photo on marble, soft studio light",
"model": "nano-banana-2",
"aspectRatio": "1:1",
"resolution": "2k"
}'
curl -X POST "https://mvp.tryunsora.com/api/v1/image-generations/create" \
-H "Authorization: Bearer uns_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Same character, new outfit, editorial look",
"model": "gpt-image-2",
"aspectRatio": "9:16",
"resolution": "2k",
"referenceImages": [
"https://cdn.example.com/ref-1.jpg"
]
}'
Errors
| HTTP | When |
|---|---|
400 | Missing/invalid prompt, model, ratio, resolution, or too many reference images |
401 | Invalid auth |
402 | Insufficient credits |
404 | User not found |
429 | Rate limit exceeded |
500 | Server error |
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Max 128 chars. Replays the same response for 24h on API key requests.
Maximum string length:
128Body
application/json
Any image model key from GET /catalog (e.g. nano-banana-2, nano-banana-pro, gpt-image-2, seedream-5.0-pro). gpt-image-1.5 maps to GPT Image 2 and seedream-v5-lite to Seedream 5.0 Pro.
Aspect ratio. Valid values depend on the model; auto uses the model's default.
Output size such as 1k, 2k or 4k, for models that offer it. Other values fall back to the model's default.
Quality tier, for models that offer it.
Public HTTPS reference image URLs. The maximum count depends on the model.