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

Create a scene

POST/v1/scenes
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
namestringrequired
min length 1 · max length 200
promptstringrequired
min length 1 · max length 10000
modelstring
default: "nano-banana-pro"
Allowed:nano-banana-pro
resolutionstring
default: "1K"
Allowed:1K2K4K
webhook_urlstring<uri>
quote_onlyboolean
default: false
quote_idstring<uuid>
optionsobject
default: {}
Show properties
aspect_ratiostring
Allowed:1:116:99:164:33:43:22:3
reference_imagesstring<uri>[]
max items 4
avatar_idstring<uuid>
product_imagestring<uri>
modestring
Allowed:ugcproductcustom
Responses
200Side-effect-free scene 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
201Scene creation started
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
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/scenes" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Morning vanity",
  "prompt": "Premium skincare bottle on a warm stone vanity",
  "model": "nano-banana-pro",
  "resolution": "1K",
  "options": {
    "aspect_ratio": "9:16",
    "mode": "product"
  }
}'
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
    }
  }
}