roasOSIdentity and first frames
Two different jobs that an input image can do, and how to tell roasOS which one you want.
An image that you attach to a request can do two very different jobs. Give the image the correct role, or the result is wrong.
- Identity. "This is the person. Keep this face and this body in every shot." roasOS sends the image to the model as a character reference.
- First frame. "The video starts on this exact picture." The model animates the picture that you gave.
A third role is close to both, and it is neither:
- Style reference. "Make it look like this." The model copies the light, the colour and the material. It does not copy the person.
The fields
| Job | Fields |
|---|---|
| Identity | avatar_id, elements |
| First frame | image_url, scene_id, scene_image |
| Last frame | end_image_url |
| Style | references |
Each model page gives the roles that the model accepts, in its Media section. Nano Banana Pro is an example. A role that the model does not accept gets 400 unsupported_option.
Choose the correct one
The same person must appear in many shots
Use identity. Create an avatar once, then send avatar_id on each request. Avatar creation generates its character reference sheet automatically: an original full-body image followed by a matching three-panel sheet. roasOS resolves the saved identity into the references supported by the selected model.
avatar_id names a roasOS gallery avatar or an avatar that your workspace already holds. Create one through POST /v1/avatar/nano-banana-pro or in the app. The plural resource route POST /v1/avatars is not a creation endpoint. GET /v1/avatars, GET /v1/avatars/{id} and DELETE /v1/avatars/{id} manage saved avatars.
POST /v1/avatar/nano-banana-pro creates an original full-body image, then generates a three-panel sheet from that image and derives its individual crops. The sheet is included in the avatar creation quote; no separate purchase or enrichment step is required.
You have the exact opening picture of the clip
Use the first frame. Send image_url, or send scene_id when the picture is a scene that roasOS made.
You want the look, not the person
Use references. Do not put a face in references and expect the face to stay the same.
Rules to remember
- A first frame carries its own identity. If the first frame already shows the correct person, do not send an identity field too. The UGC family works this way: the scene is the first frame, and the person in the scene is the person in the clip.
- Some models refuse a face. Seedance 2.5 takes reference media, and the provider's own likeness filter refuses a human face in it. It refuses a real face and a generated face. The run then fails with
provider_rejects_face_references, and roasOS refunds the reservation. Use Kling 4.0 when the person must stay the same. Refer to Seedance 2.5 and to Kling 4.0. - A real person needs a consent record on some lanes. A voice clone, an avatar lipsync and a recast onto an uploaded face each take a versioned attestation. Refer to Media rights.
- Do not describe the role in the prompt. Write what the person does and where the product is. roasOS writes the placement text.
- Do not describe the face. The identity image does that job. A written face description fights the reference.
From an image to a video
The usual sequence has three steps.
- Make the still with Nano Banana Pro, with
avatar_idfor the person andproduct_idfor the product. - Send the result URL as
image_urlto a video model. - Poll the job and read the result. Refer to Jobs.
Step 2 works because a result is an immutable object on https://cdn.roasos.com. Refer to Reference media and uploads.
One workflow does the same three steps for you, on one door: Animate a still.
Next
- The shots behind
product_id: Product kits. - Put a different person in a finished clip: Recast an actor.
- Whose face you may send: Media rights.