Skip to main content
POST
/
image-generations
/
create
curl -X POST "https://mvp.tryunsora.com/api/v1/image-generations/create" \
  -H "Authorization: Bearer uns_live_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_live_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>"
  },
  "creditsDeducted": 123,
  "creditsRemaining": 123
}
{
  "error": "<string>",
  "success": true,
  "code": "<string>",
  "message": "<string>"
}
{
  "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

HeaderRequiredDescription
AuthorizationYesBearer uns_live_* API key or Clerk JWT
Idempotency-KeyNoMax 128 chars. Replays the same response for 24h on API key requests
Content-TypeYesapplication/json

​
Request body

​
prompt
string
required
Text prompt for the image.
​
model
string
Model key. Default: nano-banana-2.
modelDisplay nameresolution valuesaspectRatio
nano-banana-2Google Nano Banana 21k, 2k, 4kauto, 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-proGoogle Nano Banana Pro1k, 2k, 4k1:1, 2:3, 3:4, 4:5, 3:2, 4:3, 5:4, 16:9, 21:9
seedream-v5-liteByteDance Seedream v5.0 Litebasic, high (quality)1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9
gpt-image-1.5OpenAI GPT-Image 1.51024x1024, 1024x1536, 1536x1024 (use as resolution)—
gpt-image-2OpenAI GPT Image 21k, 2k, 4kauto, 1:1, 9:16, 16:9, 4:3, 3:4
​
aspectRatio
string
Aspect ratio. Must be allowed for the chosen model. Default: auto (where supported).
​
resolution
string
Output size or quality tier. Must match the chosen model (see table above). Default: 2k for most models.
​
referenceImages
string[]
Reference image URLs (public HTTPS). Use for style or subject guidance. Max count depends on model (up to 14–16).
​
nsfwChecker
boolean
Enable NSFW filtering when supported by the provider pipeline.

​
Async completion

Poll Poll generation status with generation.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_live_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_live_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

HTTPWhen
400Missing/invalid prompt, model, ratio, resolution, or too many reference images
401Invalid auth
402Insufficient credits
404User not found
429Rate limit exceeded
500Server error

Authorizations

​
Authorization
string
header
required

Clerk session JWT or Unsora API key (uns_live_*)

Headers

​
Idempotency-Key
string

Optional. Replays the original response for 24h when using an API key.

Maximum string length: 128

Body

application/json
​
prompt
string
required

Text prompt for the image

​
model
string
default:nano-banana-2

Model key: nano-banana-2, nano-banana-pro, seedream-v5-lite, gpt-image-1.5, gpt-image-2

​
aspectRatio
string
default:auto

Aspect ratio; allowed values depend on model

​
resolution
string
default:2k

Output size or quality; allowed values depend on model

​
referenceImages
string<uri>[]

Reference image URLs; max count depends on model

​
nsfwChecker
boolean

Response

Job queued

​
success
boolean
required
​
generation
object
required
​
creditsDeducted
number
​
creditsRemaining
number