Skip to content
roasOS API
Esc
↑↓navigate↵open⌘Jpreview

Create a generation

Start an async generation job. Generate one Idempotency-Key for the request and reuse it only when retrying the exact same payload. Poll GET /v1/generations/{id} for status, or provide a webhook_url to be notified on completion.

POST/v1/generations
Header parameters
Idempotency-Keystringrequired
A unique string that makes retries safe. Any value 16-255 characters; reuse it only when retrying the exact same request.
min length 16 · max length 255 · matches ^[A-Za-z0-9._:-]+$
X-RoasOS-Projectstring
Optional label to group this request under one of your projects. Appears in your usage records.
min length 1 · max length 64 · matches ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$
X-RoasOS-Cost-Centerstring
Optional label to attribute this request to a cost center. Appears in your usage records.
min length 1 · max length 64 · matches ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$
Request body
requiredapplication/json
One of:
ImageGenerationCreateRequest
typestringrequired
Allowed:image
promptstringrequired
min length 1 · max length 10000
webhook_urlstring<uri>
modelstring
default: "nano-banana-pro"
Allowed:nano-banana-pronano-banana-2gpt-image-2kling-3-imageflux-2-maxgrok-imagine-image
optionsobject
default: {}
Show properties
aspect_ratiostring
min length 1 · max length 32
resolutionstring
max length 32
num_outputsinteger
min 1 · max 4
reference_imagesstring<uri>[]
max items 9
negative_promptstring
max length 2000
prompt_upsamplingboolean
seedinteger
min -2147483648 · max 2147483647
quote_onlyboolean
default: false
quote_idstring<uuid>
VideoGenerationCreateRequest
typestringrequired
Allowed:video
promptstringrequired
min length 1 · max length 10000
webhook_urlstring<uri>
modelstring
default: "kling-3"
Allowed:veo-3.1grok-imaginewan-2.7seedance-2seedance-2-progemini-omni-flashkling-o3-prokling-o3kling-o3-4kkling-3-prokling-3-4kkling-3
optionsobject
default: {}
Show properties
aspect_ratiostring
min length 1 · max length 32
resolutionstring
max length 32
durationinteger
min 1 · max 60
reference_imagesstring<uri>[]
max items 9
reference_videosstring<uri>[]
max items 3
imagestring<uri>
negative_promptstring
max length 2000
generate_audioboolean
last_framestring<uri>
multi_shotsboolean
prompt_expansionboolean
audio_urlstring<uri>
audio_urlsstring<uri>[]
max items 3
quote_onlyboolean
default: false
quote_idstring<uuid>
AudioGenerationCreateRequest
typestringrequired
Allowed:audio
promptstringrequired
min length 1 · max length 10000
webhook_urlstring<uri>
modelstring
default: "elevenlabs-v3"
Allowed:elevenlabs-v3maya-1minimax-speech-hdminimax-speech-turboqwen3-tts
optionsobject
default: {}
Show properties
voicestring
min length 1 · max length 256
speednumber
min 0.1 · max 5
pitchnumber
min -12 · max 12
stabilitynumber
min 0 · max 1
similarity_boostnumber
min 0 · max 1
languagestring
min length 1 · max length 64
quote_onlyboolean
default: false
quote_idstring<uuid>
LipsyncGenerationCreateRequest
typestringrequired
Allowed:lipsync
promptstringrequired
min length 1 · max length 10000
webhook_urlstring<uri>
modelstring
default: "ltx-lipsync"
Allowed:ltx-lipsync
optionsobjectrequired
Show properties
aspect_ratiostring
min length 1 · max length 32
imagestring<uri>required
audio_urlstring<uri>required
quote_onlyboolean
default: false
quote_idstring<uuid>
Responses
200Side-effect-free generation quote. If authorization.status is approval_required, open authorize_url, approve as a workspace owner/admin, then resubmit quote_id with the same Idempotency-Key. No credits are reserved and no provider work starts.
dataobjectrequired
Show properties
kindstringrequired
Allowed:quote
quote_idstring<uuid>required
reserved_creditsintegerrequired
min 0
expires_atstring<date-time>required
pricing_versionstringrequired
min length 1 · max length 80
authorizationobjectrequired
Show properties
Any of:
object
statusstringrequired
Allowed:auto_approved
object
statusstringrequired
Allowed:approval_required
authorize_urlstring<uri>required
max length 2048
confirmationobjectrequired
Show properties
generation_typestringrequired
Allowed:imagevideoaudiolipsyncscene
modelstringrequired
min length 1 · max length 200
modestring
min length 1 · max length 160
resolutionstring
min length 1 · max length 32
output_countinteger
min 0 · max 16
duration_secondsnumber
min 0 · max 3600
generate_audioboolean
reference_countinteger
min 0 · max 16
text_lengthinteger
min 0 · max 1000000
201Generation created and processing
dataobjectrequired
Show properties
idstring<uuid>required
typestringrequired
Allowed:imagevideoaudiolipsyncscene
statusstringrequired
Allowed:processing
modelstringrequired
min length 1 · max length 200
credits_usedintegerrequired
min 0
credits_remainingintegerrequired
min 0
estimated_secondsintegerrequired
min 0 · max 86400
created_atstring<date-time>required
400Validation error
errorobjectrequired
Show properties
codestringrequired
min length 1 · max length 128
messagestringrequired
min length 1 · max length 2000
retryablebooleanrequired
request_idstring<uuid>required
balanceinteger
min 0
requiredinteger
min 0
fieldstring
min length 1 · max length 512
statestring
min length 1 · max length 128
retryWithNewKeyboolean
parameterstring
min length 1 · max length 128
allowedstring[]
max items 100
402Insufficient credits
errorobjectrequired
Show properties
codestringrequired
min length 1 · max length 128
messagestringrequired
min length 1 · max length 2000
retryablebooleanrequired
request_idstring<uuid>required
balanceinteger
min 0
requiredinteger
min 0
fieldstring
min length 1 · max length 512
statestring
min length 1 · max length 128
retryWithNewKeyboolean
parameterstring
min length 1 · max length 128
allowedstring[]
max items 100
403The API key is not authorized for this model or request credit ceiling
errorobjectrequired
Show properties
codestringrequired
min length 1 · max length 128
messagestringrequired
min length 1 · max length 2000
retryablebooleanrequired
request_idstring<uuid>required
balanceinteger
min 0
requiredinteger
min 0
fieldstring
min length 1 · max length 512
statestring
min length 1 · max length 128
retryWithNewKeyboolean
parameterstring
min length 1 · max length 128
allowedstring[]
max items 100
409The idempotency key is already processing, has an unknown outcome, or was reused with different request data
errorobjectrequired
Show properties
codestringrequired
min length 1 · max length 128
messagestringrequired
min length 1 · max length 2000
retryablebooleanrequired
request_idstring<uuid>required
balanceinteger
min 0
requiredinteger
min 0
fieldstring
min length 1 · max length 512
statestring
min length 1 · max length 128
retryWithNewKeyboolean
parameterstring
min length 1 · max length 128
allowedstring[]
max items 100
410The supplied authoritative quote expired and must be replaced using a new idempotency key
errorobjectrequired
Show properties
codestringrequired
min length 1 · max length 128
messagestringrequired
min length 1 · max length 2000
retryablebooleanrequired
request_idstring<uuid>required
balanceinteger
min 0
requiredinteger
min 0
fieldstring
min length 1 · max length 512
statestring
min length 1 · max length 128
retryWithNewKeyboolean
parameterstring
min length 1 · max length 128
allowedstring[]
max items 100
428The supplied quote requires owner/admin spend authorization
errorobjectrequired
Show properties
codestringrequired
min length 1 · max length 128
messagestringrequired
min length 1 · max length 2000
retryablebooleanrequired
request_idstring<uuid>required
balanceinteger
min 0
requiredinteger
min 0
fieldstring
min length 1 · max length 512
statestring
min length 1 · max length 128
retryWithNewKeyboolean
parameterstring
min length 1 · max length 128
allowedstring[]
max items 100
429Rate limit, concurrency limit, or daily/monthly credit budget exceeded
errorobjectrequired
Show properties
codestringrequired
min length 1 · max length 128
messagestringrequired
min length 1 · max length 2000
retryablebooleanrequired
request_idstring<uuid>required
balanceinteger
min 0
requiredinteger
min 0
fieldstring
min length 1 · max length 512
statestring
min length 1 · max length 128
retryWithNewKeyboolean
parameterstring
min length 1 · max length 128
allowedstring[]
max items 100
503The paid request could not be claimed safely or an external billing outcome is unknown
errorobjectrequired
Show properties
codestringrequired
min length 1 · max length 128
messagestringrequired
min length 1 · max length 2000
retryablebooleanrequired
request_idstring<uuid>required
balanceinteger
min 0
requiredinteger
min 0
fieldstring
min length 1 · max length 512
statestring
min length 1 · max length 128
retryWithNewKeyboolean
parameterstring
min length 1 · max length 128
allowedstring[]
max items 100
Request
curl -X POST "https://api.roasos.com/v1/generations" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "image",
  "prompt": "string",
  "webhook_url": "<uri>",
  "model": "nano-banana-pro",
  "options": {},
  "quote_only": false,
  "quote_id": "<uuid>"
}'
Response
{
  "data": {
    "kind": "quote",
    "quote_id": "<uuid>",
    "reserved_credits": 0,
    "expires_at": "2024-01-01T00:00:00Z",
    "pricing_version": "string",
    "authorization": {
      "status": "auto_approved"
    },
    "confirmation": {
      "generation_type": "image",
      "model": "string",
      "mode": "string",
      "resolution": "string",
      "output_count": 0,
      "duration_seconds": 0,
      "generate_audio": true,
      "reference_count": 0,
      "text_length": 0
    }
  }
}