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

Run a batch

Confirm a batch quote to run it. Reserves the batch credits and starts every generation together. Retrying with the same idempotency key returns the same result.

POST/v1/generation-batches
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
batch_quote_idstring<uuid>required
Responses
201Atomically admitted generation batch
dataobjectrequired
Show properties
kindstringrequired
Allowed:generation_batch
idstring<uuid>required
statusstringrequired
Allowed:processing
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}$
generation_idstring<uuid>required
typestringrequired
Allowed:imagevideoaudiolipsync
statusstringrequired
Allowed:processing
modelstringrequired
min length 1 · max length 200
reserved_creditsintegerrequired
min 0
total_reserved_creditsintegerrequired
min 0
created_atstring<date-time>required
400Invalid confirmation request
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
403Quote approval or API key spend policy denied the 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
404Batch quote not found
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
409Quote, idempotency, materialization, or dispatch authority conflict
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 or active-generation quota 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
503Billing, database authority, or recovery outcome is temporarily 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" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
  "batch_quote_id": "99999999-9999-4999-8999-999999999999"
}'
Response
{
  "data": {
    "kind": "generation_batch",
    "id": "<uuid>",
    "status": "processing",
    "items": [
      {
        "item_id": "string",
        "generation_id": "<uuid>",
        "type": "image",
        "status": "processing",
        "model": "string",
        "reserved_credits": 0
      }
    ],
    "total_reserved_credits": 0,
    "created_at": "2024-01-01T00:00:00Z"
  }
}