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

Quote a batch

Price a whole batch of generations at once. No credits are charged and nothing runs yet. Sending the same batch again returns the same quote; changing or reordering items creates a new one.

POST/v1/generation-batches/quotes
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
itemsobject[]required
min items 1 · max items 8
Show properties
Array of object
item_idstringrequired
min length 1 · max length 64 · matches ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$
requestobjectrequired
Show properties
Any of:
object
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
object
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
object
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
object
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
Responses
200Side-effect-free all-items-valid batch quote
dataobjectrequired
Show properties
kindstringrequired
Allowed:batch_quote
batch_quote_idstring<uuid>required
itemsobject[]required
min items 1 · max items 8
Show properties
Array of object
item_idstringrequired
min length 1 · max length 64 · matches ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$
reserved_creditsintegerrequired
min 0
confirmationobjectrequired
Show properties
generation_typestringrequired
Allowed:imagevideoaudiolipsync
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
total_reserved_creditsintegerrequired
min 0
pricing_versionstringrequired
min length 1 · max length 80
expires_atstring<date-time>required
authorizationobjectrequired
Show properties
Any of:
object
statusstringrequired
Allowed:auto_approved
object
statusstringrequired
Allowed:approval_required
authorize_urlstring<uri>required
max length 2048
400The batch or one indexed item is invalid; no quote is issued
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 one or more requested models
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 parent idempotency key was reused for a different ordered batch
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
429Write rate limit 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
503Generation preparation, media evidence, pricing, or quote authority is unavailable
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/generation-batches/quotes" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "item_id": "hero-image",
      "request": {
        "type": "image",
        "prompt": "Studio product photograph of a cobalt hydration bottle",
        "model": "nano-banana-pro",
        "options": {
          "aspect_ratio": "1:1",
          "resolution": "1K",
          "num_outputs": 1
        }
      }
    },
    {
      "item_id": "hero-video",
      "request": {
        "type": "video",
        "prompt": "Slow push-in on a skincare bottle in soft morning light",
        "model": "kling-3",
        "options": {
          "aspect_ratio": "9:16",
          "resolution": "auto",
          "duration": 5,
          "generate_audio": true
        }
      }
    }
  ]
}'
Response
{
  "data": {
    "kind": "batch_quote",
    "batch_quote_id": "<uuid>",
    "items": [
      {
        "item_id": "string",
        "reserved_credits": 0,
        "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
        }
      }
    ],
    "total_reserved_credits": 0,
    "pricing_version": "string",
    "expires_at": "2024-01-01T00:00:00Z",
    "authorization": {
      "status": "auto_approved"
    }
  }
}