roasOSGet one catalog model
One model from the catalog. A few model ids exist in several families (nano-banana-pro is an image, a scene, and an avatar model); read those as /v1/catalog/{family}/{model}.
One model from the catalog. A few model ids exist in several families (nano-banana-pro is an image, a scene, and an avatar model); read those as /v1/catalog/{family}/{model}.
Authorization
bearerAuth API key authentication. Use your API key as the bearer token: Authorization: Bearer roasos_sk_...
In: header
Path Parameters
Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/v1/catalog/string"{ "data": { "key": "string", "id": "string", "family": "string", "endpoint": "string", "modes": [ "string" ], "fields": { "property1": { "type": "string", "enum": [ "string" ], "min": 0, "max": 0, "max_chars": 0, "max_items": 0, "required": true, "default": "string", "modes": [ "string" ], "mode_rules": { "property1": { "required": true, "max": 0 }, "property2": { "required": true, "max": 0 } }, "pinned": true }, "property2": { "type": "string", "enum": [ "string" ], "min": 0, "max": 0, "max_chars": 0, "max_items": 0, "required": true, "default": "string", "modes": [ "string" ], "mode_rules": { "property1": { "required": true, "max": 0 }, "property2": { "required": true, "max": 0 } }, "pinned": true } }, "media": { "property1": { "max_items": 1, "max_bytes": 1, "content_types": [ "string" ], "min_seconds": 0, "max_seconds": 0 }, "property2": { "max_items": 1, "max_bytes": 1, "content_types": [ "string" ], "min_seconds": 0, "max_seconds": 0 } }, "result": { "kind": "string", "fields": { "property1": { "type": "string", "enum": [ "string" ], "min": 0, "max": 0, "max_chars": 0, "max_items": 0, "required": true, "default": "string", "modes": [ "string" ], "mode_rules": { "property1": { "required": true, "max": 0 }, "property2": { "required": true, "max": 0 } }, "pinned": true }, "property2": { "type": "string", "enum": [ "string" ], "min": 0, "max": 0, "max_chars": 0, "max_items": 0, "required": true, "default": "string", "modes": [ "string" ], "mode_rules": { "property1": { "required": true, "max": 0 }, "property2": { "required": true, "max": 0 } }, "pinned": true } } }, "credits": { "unit": "string", "examples": { "property1": 0, "property2": 0 } }, "provider_endpoint_ids": [ "string" ], "pricing_keys": [ "string" ], "provider_not_exposed": { "property1": null, "property2": null }, "provider_pricing": { "text": "string", "source": "string" }, "hidden": true, "deprecated": { "replacement": "string", "note": "string" }, "guide": { "family": "string", "best_for": "string", "rules": [ "string" ], "example": "string" }, "expected_generation_ms": { "p50_ms": 1, "p90_ms": 1, "basis": "measured" } }}List ad formats
Every ad format roasOS makes: video formats, product effects, TikTok slideshows and statics. Each format has its premise, its beats, how to shoot it, what breaks it, what it needs, its default model roles (resolve them in `GET /v1/catalog` roles) and the pack skill that runs it. Ask for a format by name in `POST /v1/agent/completions`. This call is free.
Run nano-banana-pro (image)
Submit a image job to nano-banana-pro. The request carries the real fields of this model; there is no hidden switch on a model parameter. Send `quote_only: true` to price the request for free, then send the same body with the returned `quote_id` to run it. Attach identity, product, or a first frame by resource id (`avatar_id`, `product_id`, `scene_id`) or by a workspace-owned `cdn.roasos.com` URL. Any other URL is `400 reference_media_not_workspace_owned`. Pass a `webhook_url` and roasOS POSTs you the same job envelope `GET /v1/jobs/{id}` returns when the job finishes, signed with `X-RoasOS-Signature` and retried on failure. The URL must be HTTPS and reachable (`400 invalid_url` otherwise), and first-party keys cannot register webhooks (`400 webhook_url_not_supported_for_key`). See **Webhooks** above for verification. Polling `links.status` works too.