AI Character Consistency API — Reference Packs and Retry Rules

Image Reference vs. Video Reference-to-Video

Image reference models (MiniMax Subject Reference, Ideogram Character, Seedance 2 Character, Gemini Omni Character) take one or a few reference photos of a subject and generate a new still image that keeps that subject recognizable in a different pose, outfit, or setting. Reference-to-video models (Seedance 2.5 Omni Reference, Wan 3.0, Veo 3.1, Kling O1, Vidu Q2, MiniMax H3) do the same thing but output a video — the character stays consistent across every frame of motion, not just one static composition.

Muapi exposes 40+ character/reference models across image and video through the same unified REST pattern: one API key, one request/poll flow, pay-per-generation pricing with no subscription.

Reference Pack Size — Verified Limits

How many reference images a model accepts varies a lot, and it's a real constraint, not a UI preference — submitting more images than a model's images_list limit allows will fail the request. Verified against each model's live input schema:

Multi-Modal References — Beyond Just a Photo

The most capable reference models don't stop at images. Seedance 2.5 Omni Reference and Wan 3.0 Reference-to-Video both accept a videos_list and an audios_list alongside the image references, letting the model carry over motion style or voice, not just visual appearance. MiniMax H3 Reference-to-Video exposes this as three explicit fields — reference_images, reference_videos, reference_audios — so you can mix visual identity from a photo with a voice sample and a motion clip in one request. Gemini Omni Character takes this further into image editing entirely: it builds a character asset from images plus an audio_ids reference for voice, ahead of any generation step.

Representative Models

Writing Controlled Prompts for Reference Models

• Describe the new scene, not the subject. The reference images already establish who the character is — the prompt should describe the pose, setting, action, or camera move, not re-describe the character's appearance.
• Use multiple angles when the pack allows it. A front, a 3/4, and a profile shot of the same subject give models with a larger reference limit (Wan 3.0, Seedance 2.5 Omni Reference) more identity signal than three near-identical front shots.
• Keep lighting and background simple in reference photos. A cluttered or heavily stylized reference image can bleed unwanted background elements into the generated result.
• Build your own test set before batch-producing. Run the same reference pack through 3–5 different prompts and compare results side by side — consistency quality varies by pose extremity and scene complexity, and there is currently no published third-party benchmark to substitute for testing your specific character.

Avoiding Async Failures — Task-Type Hints and Retries

Seedance 2.5 Omni Reference exposes an omni_reference_task_type field (auto/reference/edit/extend) specifically so that ratio/duration constraint mismatches get caught at submission time instead of failing asynchronously after you've already waited on the job. edit and extend both require aspect_ratio: "adaptive", and edit additionally requires duration: -1 — leaving these as their defaults on the wrong task type is a common cause of a late, avoidable failure. Note the model still re-derives the actual task type from the prompt during processing, so a mismatch can still surface as an async error even with the hint set correctly — treat the field as a submission-time sanity check, not a guarantee.

How to Call a Character Consistency Model

1. Host your reference images. Upload via POST /api/v1/upload_file, or use any publicly reachable URLs.
2. Submit the request. POST /api/v1/{model-slug} with images_list (or image_url for single-reference models) and a prompt describing the new scene.
3. Poll for completion. Check GET /api/v1/predictions/{request_id}/result until status is completed, then download the result.

curl -X POST https://api.muapi.ai/api/v1/seedance-2.5-omni-reference \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "images_list": [
      "https://example.com/character-front.jpg",
      "https://example.com/character-side.jpg"
    ],
    "prompt": "the character walking through a neon-lit city street at night",
    "omni_reference_task_type": "reference",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

import requests

response = requests.post(
    "https://api.muapi.ai/api/v1/seedance-2.5-omni-reference",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "images_list": [
            "https://example.com/character-front.jpg",
            "https://example.com/character-side.jpg",
        ],
        "prompt": "the character walking through a neon-lit city street at night",
        "omni_reference_task_type": "reference",
        "duration": 5,
        "aspect_ratio": "16:9",
    },
)
request_id = response.json()["request_id"]

result = requests.get(
    f"https://api.muapi.ai/api/v1/predictions/{request_id}/result",
    headers={"x-api-key": "YOUR_API_KEY"},
)
print(result.json())

Frequently Asked Questions