Character reference sheets

Every new avatar includes an original full-body image and a matching character reference sheet in one creation flow. roasOS first generates a 4K vertical 2:3 image of the character, then uses that exact image to generate a 4K landscape 16:9 sheet. This preserves more detail in the original image while giving later generations multiple views of the same identity.

The sheet has three panels, from left to right:

The views share the same face, hairstyle, outfit, and lighting. They provide identity references rather than training a custom model, so identical likeness in every later output is not guaranteed.

Create an avatar

Use the normal avatar creation flow in the app or POST /v1/avatar/nano-banana-pro. One quote covers both generation stages; there is no separate sheet purchase.

First request an avatar creation quote:

curl -X POST "https://api.roasos.com/v1/avatar/nano-banana-pro" \
  -H "Authorization: Bearer $ROASOS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: character-create-001" \
  -d '{"description":"An adult spokesperson with short brown hair wearing a navy shirt.","name":"Alex","mode":"manual","quote_only":true}'

Submit the returned quote using the same idempotency key and creation fields:

curl -X POST "https://api.roasos.com/v1/avatar/nano-banana-pro" \
  -H "Authorization: Bearer $ROASOS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: character-create-001" \
  -d '{"description":"An adult spokesperson with short brown hair wearing a navy shirt.","name":"Alex","mode":"manual","quote_id":"<quote-id>"}'

The creation response is an avatar job. Poll its job link; its completed result includes avatar_id, reference_sheet, portrait_url, and full_body_url. Then read GET /v1/avatars/{avatar_id} until the saved avatar is available: publication can finish shortly after rendering. The creation costs 20 credits: 10 for the original image and 10 for the matching sheet. Read the quote for the authoritative price. Cropping the three panels does not add image generation charges.

Saved identity

GET /v1/avatars/{id} exposes the generated sheet as images.reference_sheet. images.full_body is the original full-body image and images.front is the face crop. The avatar library shows the original image first, with the sheet and its individual views available in the detail view.

Continue sending avatar_id to supported generation endpoints. roasOS chooses the reference representation supported by the model:

• Image and scene generation can use the character sheet as an identity reference.
• Reference-to-video generation uses the full sheet as the character identity reference.
• Kling identity elements pair a single frontal crop with the full sheet as the supporting identity reference.
• Lipsync retains a single source image; an explicit source image takes precedence.
• Motion control uses the supplied subject image and driving video.
• A sheet never automatically becomes a video's first frame.

See Identity and first frames for the difference between identity references and an image to animate. Model-specific restrictions still apply, including face-reference filters.

Existing avatars and recovery

Older avatars remain usable with their existing portrait and full-body references. Opening or selecting an older avatar does not start a paid generation.

A creation job continues after you close the page. Recovery reuses completed stages: if the original image is ready, sheet generation uses that saved image; if the sheet is ready, cropping and publication use the saved sheet. Repeat the original idempotency key to recover the same request; use a new key only when deliberately creating another avatar.

White studio and facial detail

New characters keep a pure white seamless studio background in both the original and the sheet. For realistic characters, soft studio light preserves facial shape and true complexion, with restrained skin texture and natural eyes and hair. The face panel is framed at head-and-shoulders scale for usable identity detail. Requested illustration, anime, and other styles retain their medium.