> ## Documentation Index
> Fetch the complete documentation index at: https://tryunsora.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create image
> Queue an AI image generation job and poll until complete.
Creates an image generation job. Credits are deducted when the job is queued. Poll [Poll generation status](/api-reference/image/poll-status) with the returned `generation.id` until `status` is `COMPLETED` or `FAILED`.
## Headers
| Header | Required | Description |
| ----------------- | -------- | -------------------------------------------------------------------- |
| `Authorization` | Yes | `Bearer uns_live_*` 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
Text prompt for the image.
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` |
Aspect ratio. Must be allowed for the chosen `model`. Default: `auto` (where supported).
Output size or quality tier. Must match the chosen `model` (see table above). Default: `2k` for most models.
Reference image URLs (public HTTPS). Use for style or subject guidance. Max count depends on model (up to 14–16).
Enable NSFW filtering when supported by the provider pipeline.
## Async completion
Poll [Poll generation status](/api-reference/image/poll-status) with `generation.id` until `status` is `COMPLETED` or `FAILED`. Webhooks are not supported on the public API.
## Response
```json theme={null}
{
"success": true,
"generation": {
"id": "cm123abc",
"status": "QUEUED"
},
"creditsDeducted": 5,
"creditsRemaining": 95
}
```
## Example
```bash Basic theme={null} theme={null}
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"
}'
```
```bash With references theme={null} theme={null}
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
| 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 |
## OpenAPI
````yaml POST /image-generations/create
openapi: 3.1.0
info:
title: Unsora API
version: 1.2.0
description: >-
Public API for Unsora integrations. Authenticate with Clerk JWT or
uns_live_* API key. API keys are rate-limited to 60 requests/minute and
support idempotency keys. Async jobs complete via polling GET
/image/status/{id}.
servers:
- url: https://mvp.tryunsora.com/api/v1
description: Versioned API (recommended)
security: []
tags:
- name: Clippings
- name: Connect
- name: Image Generations
- name: Music Generations
- name: Influencer Studio
- name: Posts
- name: Thumbnails
- name: User
- name: Video Generations
paths:
/image-generations/create:
post:
tags:
- Image Generations
summary: Create image generation job
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
type: string
maxLength: 128
description: >-
Optional. Replays the original response for 24h when using an API
key.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateImageGenerationRequest'
responses:
'200':
description: Job queued
content:
application/json:
schema:
$ref: '#/components/schemas/CreateImageGenerationResponse'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'402':
description: Insufficient credits
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded
security:
- bearerAuth: []
components:
schemas:
CreateImageGenerationRequest:
type: object
properties:
prompt:
type: string
description: Text prompt for the image
model:
type: string
default: nano-banana-2
description: >-
Model key: nano-banana-2, nano-banana-pro, seedream-v5-lite,
gpt-image-1.5, gpt-image-2
aspectRatio:
type: string
default: auto
description: Aspect ratio; allowed values depend on model
resolution:
type: string
default: 2k
description: Output size or quality; allowed values depend on model
referenceImages:
type: array
items:
type: string
format: uri
description: Reference image URLs; max count depends on model
nsfwChecker:
type: boolean
required:
- prompt
CreateImageGenerationResponse:
type: object
properties:
success:
type: boolean
generation:
type: object
properties:
id:
type: string
status:
type: string
enum:
- QUEUED
- PROCESSING
- COMPLETED
- FAILED
required:
- id
- status
creditsDeducted:
type: number
creditsRemaining:
type: number
required:
- success
- generation
ErrorResponse:
type: object
properties:
success:
type: boolean
error:
type: string
code:
type: string
message:
type: string
required:
- error
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Clerk session JWT or Unsora API key (uns_live_*)
````