Seedance 2.0 API

To maintain a character's identity across multiple scenes, use one of two workflows:

Option A: @character:<id> inline (Simplest)

1. Generate a character sheet using create_character.
2. Wait for completion to get the request_id.
3. Reference the character in any prompt using the syntax @character:<request_id>.

Option B: consistent_video() (Highest Fidelity)

1. Generate a character sheet.
2. Retrieve the sheet URL from the outputs[0] field after completion.
3. Pass that URL directly as the @image1 reference in an Image-to-Video (I2V) request.

from seedance_api import SeedanceAPI
api = SeedanceAPI()

# Step 1 — generate a character sheet
char = api.create_character(
    images_list=["https://example.com/person.jpg"],
    outfit_description="cyberpunk jacket with neon accents, glowing visor",
)
char_id = char["request_id"]
api.wait_for_completion(char_id)

# Step 2 — reference the character inline
video = api.text_to_video(
    prompt=f"@character:{char_id} rides a motorcycle through a neon-lit city at night",
    aspect_ratio="16:9",
    duration=5,
)
result = api.wait_for_completion(video["request_id"])
print(f"Video: {result['outputs'][0]}")

Character consistency is achieved through a two-step workflow that allows you to generate videos featuring the same fictional character across multiple scenes.

1. Create a character sheet: You provide 1–3 reference photos of a person and a description of their outfit/style. The API generates a high-resolution (4K / 21:9) structured character sheet containing various views (front, back, side, action poses, facial expressions, and accessories).
2. Use the character in videos: You can then reference this character in video generation using one of two methods:
   • Inline Reference (@character:<request_id>): The easiest method. You embed a special tag in your prompt, and the server automatically resolves the character sheet.
   • Direct Image-to-Video (consistent_video()): The high-fidelity method. You pass the sheet_url directly as the primary image in an Image-to-Video request. This provides the model with the full 4K sheet at inference time, leading to tighter face and identity preservation.

The simplest way to use a character is to embed the character's request_id directly into your prompt using the syntax @character:<request_id>. This works across Text-to-Video (T2V), Image-to-Video (I2V), and Omni-Reference workflows.

Examples:

Text-to-Video:

{
  "prompt": "@character:ab539e5f-1234-... walks through a rain-soaked neon city at night",
  "aspect_ratio": "16:9",
  "duration": 5,
  "quality": "basic"
}

Image-to-Video:

{
  "prompt": "@character:ab539e5f-1234-... looks out over the city from a rooftop",
  "images_list": ["https://example.com/background.jpg"],
  "aspect_ratio": "16:9",
  "duration": 5
}

Omni-Reference (image + video + audio):

{
  "prompt": "@character:ab539e5f-1234-... enters the scene and picks up the artifact",
  "aspect_ratio": "16:9",
  "duration": 6,
  "images_list": ["https://example.com/scene.jpg"],
  "video_files": ["https://example.com/intro_clip.mp4"]
}

Multiple Characters: You can reference multiple characters in a single prompt: "@character:ab539e5f-... and @character:cd781a2b-... face each other in the arena"

To ensure the highest quality character consistency, follow these best practices:

• Reference photos: Use 2–3 clear, well-lit shots including a frontal view, a 3/4-angle, and a side profile. Avoid heavy shadows or obscured faces.
• Outfit description: Be highly specific about materials, colors, and distinctive details to avoid generic results.
• Prompt framing: Focus your prompt on what the character does (actions/environment) rather than what they look like, as the character sheet already provides the visual identity.
• Consistency across scenes: Reuse the same char_id or sheet_url for every shot in a series.
• Handling drifting features: If the @character:<id> method causes the character's face to drift or change, switch to consistent_video() to anchor the generation directly to the 4K sheet image.
• Complex movement: For scenes with complex character actions, use duration=8 and quality=high for smoother motion.