roasOS
API referenceGenerations

List generations

GET
/v1/generations

Authorization

bearerAuth
AuthorizationBearer <token>

API key authentication. Use your API key as the bearer token: Authorization: Bearer roasos_sk_...

In: header

Query Parameters

cursor?string

Opaque composite pagination cursor from the previous response. Do not parse or construct it.

limit?integer

Number of items to return

Range1 <= value <= 100
Default20
type?string

Filter by generation type. Avatars and scenes (created via /v1/avatars and /v1/scenes) are stored in the same table and are returned here too, so they can be filtered as avatar / scene.

Value in

  • "image"
  • "video"
  • "audio"
  • "lipsync"
  • "avatar"
  • "scene"
status?string

Filter by status

Value in

  • "pending"
  • "processing"
  • "completed"
  • "failed"

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/generations"
{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "type": "string",      "status": "pending",      "model": "string",      "prompt": "string",      "credits_used": 0,      "error_message": "string",      "output": {        "url": "http://example.com",        "images": [          "http://example.com"        ],        "scene_id": "861eef56-1159-4a95-802f-abab2d0cc192",        "avatar_id": "ceaabbd8-6fdf-460c-878c-7d0ae67338c0",        "reference_sheet": "http://example.com",        "portrait_url": "http://example.com",        "full_body_url": "http://example.com",        "provider_seed": -2147483648      },      "created_at": "2019-08-24T14:15:22Z",      "completed_at": "2019-08-24T14:15:22Z"    }  ],  "meta": {    "cursor": "string",    "has_more": true  }}

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.

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.