AI avatar conversation video API: two speakers in one dialogue

To make a two-person AI avatar conversation video with the Sume API, render each speaker's turns as separate POST /v1/avatar-1.0/talking-video jobs, one avatar per job, then cut the turns together in speaking order with POST /v1/timeline-1.0/render. A single avatar video cannot hold both speakers.

The rules below come from Sume's Generate avatar video, Timeline audio, Timeline 1.0, and Timeline compose docs, read on 2026-09-26.

Why can't one avatar video hold both speakers?

Current execution supports one resolved avatar per final video. Multi-scene video_inputs can name an avatar per scene, but distinct scene avatars are rejected, and the API currently answers 400 with "Use one avatar for the full video." Scenes are for one presenter; see Multi-scene avatar video API for that case.

How do I plan the turns?

Write the dialogue as alternating turns and give each speaker a ready avatar handle of their own, one you created or a public one from avatar catalog search. Then shape the jobs around the length window:

• Each job must be estimated at 4-60 seconds. Merge a speaker's consecutive lines into one job.
• A very short reply can fall under 4 seconds. Fold it into a longer turn, or render it as multi-scene video_inputs with an extra voice.type: "silence" beat, which takes a required duration.
• Send the same aspect_ratio for both speakers, so every slot shares one frame shape.

How do I cut the turns together?

Timeline builds the finished MP4 on one audio spine, so the dialogue audio comes first:

• Detach each turn's audio with POST /v1/audio-detach; its default output is a sample-exact wav.
• Join the turns in speaking order with Timeline audio operation: "concat": 1-20 parts that must share one channel layout. The result is one audio_url plus segments[], whose start values are the offsets for video[].start.
• Render with that file as audio.url and one video[] slot per turn, alternating speakers. Add a transition to later slots, or leave them as cuts.

curl -X POST https://api.sume.com/v1/timeline-1.0/render \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: dialogue-assemble-01" \
  -d '{
    "audio": {
      "url": "https://media.sume.com/artifacts/artf_demo/dialogue.wav",
      "duration_seconds": 31
    },
    "video": [
      { "source_url": "https://media.sume.com/artifacts/artf_demo/host-1.mp4", "start": 0, "duration": 12 },
      { "source_url": "https://media.sume.com/artifacts/artf_demo/guest-1.mp4", "start": 12, "duration": 9 },
      { "source_url": "https://media.sume.com/artifacts/artf_demo/host-2.mp4", "start": 21, "duration": 10 }
    ]
  }'

Can both speakers be on screen at once?

Not as two talking clips with the documented tools. The one surface for two sources on screen, Timeline compose, puts one still and one video in one frame, so the closest layout is a still of the listener beside, above, or below the speaker's clip. Grab the still with video frames, send it as image.url with operation: "stack", and drop the composed MP4 into a video[] slot. The Timeline spine supplies the audio at assemble time.

What are the limits?

Every URL in these steps must be a media.sume.com artifact or asset of your workspace, and completed avatar video results can include public media.sume.com video artifacts.

What does a conversation video cost?

Each turn bills at the avatar-video rate for its length and tier: $0.184/s standard, $0.245/s plus, $0.55/s max (no product image). Detach, concat, and compose are flat per-job rates listed on the Audio detach, Timeline audio, and Timeline compose pages. The render is listed at $0.10 per output minute on API pricing. Each of these is plus a 5.5% agent fee by default.