Reference media and uploads

Each model endpoint takes media in one of two forms. Both forms give roasOS an immutable object on https://cdn.roasos.com that your workspace owns. roasOS resolves the object before the quote, so the price and the provider payload are pinned to exact bytes.

Each media URL must be a workspace-owned object on https://cdn.roasos.com. Any other URL gets 400 reference_media_not_workspace_owned. Your own upload whose bytes have not landed yet gets 409 upload_not_ready instead: send the bytes, then poll GET /v1/uploads/{id} until status is ready. roasOS does not download from a third-party URL at generation time.

A Discover creative is a competitor's ad. roasOS accepts one in the reference roles and the edit roles; you are responsible for the rights to it. Refer to Media rights.

Form A — a resource id

The workspace already holds the object. roasOS resolves the id to its CDN URLs and applies the role for you.

Field	Resource	Resolves to
`avatar_id`	an avatar	the character reference sheet or individual views supported by the model, as identity
`product_id`	a product	the product images of the product kit
`scene_id`	a scene	the scene image, as the first frame
`voice_id`	a saved voice	the provider voice of your clone

Read the resources with GET /v1/avatars, GET /v1/scenes, GET /v1/products and GET /v1/voices. Each read costs 0 credits.

A face or a voice of a real person needs a consent record on some lanes. Refer to Media rights.

Form B — a CDN URL

Any https://cdn.roasos.com object that your workspace owns:

the result of an earlier job, from GET /v1/jobs/{id}/result;
a file that you uploaded;
an object of your gallery.

roasOS makes sure that your workspace owns the object and that the object is immutable.

Roles are fields, not positions

You never count positions in a list. You name the role, and roasOS orders the images for the provider and writes the placement text.

Role field	Meaning
`references`	style and appearance references
`product_images`	product reference images
`elements`	identity: one frontal image and more views, per person or object
`image_url`	the first frame, or the single source image
`end_image_url`	the last frame
`video_urls`	reference videos
`audio_urls`	reference or driving audio

One role has one name in every family. Each model page has a Media section that gives the roles, the item counts, the file sizes and the content types of that model. A role that the model does not accept gets 400 unsupported_option.

Put your own file on the CDN

POST /v1/uploads has two modes.

Direct. Send the kind, the content type and the byte length. roasOS gives you a one-use write target.

{ "kind": "image", "content_type": "image/png", "byte_length": 812004 }

The response has id, status, put_url, put_headers and limits. POST the exact bytes to put_url with put_headers. The engine also accepts PUT on that URL. Then poll GET /v1/uploads/{id} until status is ready. The response then has the CDN URL in url.

kind is image, video or audio. limits gives the max_bytes and the allowed_content_types of that kind. One object is 100 MB at most.

Import. Send a public https source_url in place of the bytes. roasOS fetches the file, checks it and stores it. The response is the same. Use this mode when the file is on your own site.

{ "kind": "image", "source_url": "https://example.com/bottle.png" }

The API reference publishes both upload operations: POST /v1/uploads and GET /v1/uploads/{id}. Each one costs 0 credits. An agent calls the same two operations with the tools roasos_create_upload and roasos_get_upload.

Prompts stay clean

Do not describe the placement of a reference in your prompt. roasOS adds the placement text for you: it tells the model which image is the person, which is the product, and which is style only. Send a raw prompt.

Which role an image does: Identity and first frames.
The shots behind product_id: Product kits.
Whose media you may send: Media rights.
Cut and join the results: Assembly.