● tokenstore

Using Reference Images for Consistent Faces and Bodies

How to attach up to nine reference images to a Nureta image task so faces, bodies, and tattoos stay consistent across a whole set — including the upload/presign flow.

3 min read

A text prompt gives you a new person every time. Reference images give you the same person every time. When you attach one or more reference images to an image task, seahorse-image carries the identity — face, body, and skin markings — from those references into the render, so a set of images looks like one character instead of a lineup of strangers.

This is what makes a coherent gallery, a character sheet, or a series that reads as the same model across dozens of shots. This guide covers how many references you can send, what actually carries across, and how to get an image into the system if it is not already hosted at a public URL.

Skin markings and tattoos are preserved from the reference, not re-invented per image. That is the difference between a character who has the same ink in every shot and one whose tattoos flicker and drift from render to render.

How many references you can send

An image task takes exactly one text prompt plus up to nine optional image_url reference images. More references give the model more angles and more evidence of the same person, which tightens consistency — a front view, a profile, and a full-body shot together pin identity far better than a single cropped headshot. Start with two or three clean references and add more only if a feature is drifting.

What carries across

References anchor identity: facial structure, hair, body type, and distinguishing marks like tattoos, freckles, and scars. What the references do not lock is the pose, the act, the framing, or the setting — that still comes from your prompt. So the pattern is: references say who, the prompt says what and how. You can put your character into any pose or act you can describe while keeping the same face and body throughout.

Uploading a reference image

If your reference already lives at a public HTTPS URL, just pass it as image_url.url. If it is a local file, upload it first: ask the upload endpoint for a short-lived signed URL, PUT the bytes straight to storage, then pass the returned assetUrl into your generation task. Uploading is free — you are only billed when you create the image.

# 1. Ask for a signed upload URL.
UPLOAD=$(curl -s -X POST "$TOKENSTORE_URL/api/v3/contents/uploads" \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"fileName": "face.jpg", "contentType": "image/jpeg"}')
ASSET_URL=$(echo "$UPLOAD" | jq -r .assetUrl)
UPLOAD_URL=$(echo "$UPLOAD" | jq -r .uploadUrl)

# 2. PUT the bytes (same Content-Type, no auth header).
curl -s -X PUT "$UPLOAD_URL" -H "Content-Type: image/jpeg" --data-binary @face.jpg

# 3. Reference ASSET_URL when creating the image task.
curl -s -X POST "$TOKENSTORE_URL/api/v3/images/generations/tasks" \
  -H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
  -d '{
    "model": "seahorse-image",
    "content": [
      { "type": "text", "text": "the same woman standing in a doorway, nude, soft backlight" },
      { "type": "image_url", "image_url": {"url": "'"$ASSET_URL"'"} }
    ],
    "size": "2K"
  }'

Presigning is capped at 30 requests per minute per key, which is plenty for building a reference set — request one signed URL per file.

Building a consistent set

To produce a series, lock your references once and reuse them across every request, changing only the prompt. Generate your character, pick the two or three cleanest renders as your canonical references, and pass that same set into each new image. Keep the reference images sharp, well-lit, and face-forward where possible — a blurry or heavily shadowed reference gives the model less to hold onto and consistency slips.

Where to go next

Build a set in the playground →
Using Reference Images for Consistent Faces and Bodies — Nureta Guides