roasOS
API referenceWorkflows

Analyze an ad

Break one ad down into its structure. A video returns numbered shots with timings, camera, action, per-shot dialogue, on-screen text and product moments, plus a transcript, a character sheet, the global style and the insights. A still returns the layout, the copy by role, the product placement, the person, the style and a recreate prompt with {PRODUCT} and {PERSON} placeholders. Send exactly one source: `video_url`, `image_url` or `discover_item_id`. Set `quote_only: true` to see the price for free, then send the same body with the returned `quote_id` to run it. A still costs 1 credit and a video costs 2. An analysis this workspace can already reuse is a cache hit and costs nothing. The run is asynchronous: read it at `/v1/workflows/analyses/{id}`.

POST
/v1/workflows/analyze

Break one ad down into its structure. A video returns numbered shots with timings, camera, action, per-shot dialogue, on-screen text and product moments, plus a transcript, a character sheet, the global style and the insights. A still returns the layout, the copy by role, the product placement, the person, the style and a recreate prompt with {PRODUCT} and {PERSON} placeholders.

Send exactly one source: video_url, image_url or discover_item_id. Set quote_only: true to see the price for free, then send the same body with the returned quote_id to run it. A still costs 1 credit and a video costs 2. An analysis this workspace can already reuse is a cache hit and costs nothing.

The run is asynchronous: read it at /v1/workflows/analyses/{id}.

Authorization

bearerAuth
AuthorizationBearer <token>

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

In: header

Header Parameters

Idempotency-Key*string

A unique string that makes retries safe. Any value 16-255 characters; reuse it only when retrying the exact same request.

Match^[A-Za-z0-9._:-]+$
Length16 <= length <= 255
X-RoasOS-Project?string

Optional label to group this request under one of your projects. Appears in your usage records.

Match^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$
Length1 <= length <= 64
X-RoasOS-Cost-Center?string

Optional label to attribute this request to a cost center. Appears in your usage records.

Match^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$
Length1 <= length <= 64

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/workflows/analyze" \  -H "Idempotency-Key: stringstringstri" \  -H "Content-Type: application/json" \  -d '{}'
{  "data": {    "schema_version": "workflow-analysis@1",    "kind": "workflow_analysis",    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "workflow": "analyze",    "analysis_kind": "image",    "cache_disposition": "cache_hit",    "maximum_credits": 0,    "pricing_version": "string",    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z",    "status": "quoted",    "reserved_credits": 0,    "quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992",    "expires_at": "2019-08-24T14:15:22Z",    "authorization": {      "status": "auto_approved"    }  }}