Timeline audio segments: re-base video start times after concat

A timeline audio concat returns segments[] with index, start and duration_seconds; the docs call these the offsets to re-base Timeline 1.0 video[].start against. When each video slot covers one part, use that segment's start as the slot's start, and the joined audio_url as audio.url.

What does the mapping look like?

Example values, not a real job. Two lines were concatenated; slot 1 must start at 0.

Which timeline rules still apply?

video[0].start must be 0 and later starts must increase, or the render fails with timeline_must_start_at_zero or invalid_segment_timing. Declared starts are authoritative; the compiler compensates for transitions and never pre-shifts them. Coverage may trail the spine by at most 0.5 s. See the Timeline docs.

How do I check before paying?

Call POST /v1/timeline-1.0/plan. It is unbilled, needs no Idempotency-Key, and returns duration_seconds, segment_count, billable_minutes and estimated_cost_usd_micros. It cannot predict short-source pad or loop warnings.

curl -X POST https://api.sume.com/v1/timeline-1.0/plan \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio": {
      "url": "https://media.sume.com/artifacts/artf_demo/joined.wav",
      "duration_seconds": 3.6
    },
    "video": [
      { "source_url": "https://media.sume.com/artifacts/artf_demo/a.mp4", "start": 0, "duration": 1.9 },
      { "source_url": "https://media.sume.com/artifacts/artf_demo/b.mp4", "start": 1.9, "duration": 1.7 }
    ]
  }'

How does the job run?

Timeline jobs default to mode: "async". Pass mode: "sync" to wait up to 30 seconds for a 200 finished job, or you get 202 and poll GET /v1/jobs/:id/status and GET /v1/jobs/:id/result; there is no separate GET for the audio or render job. Idempotency-Key is required on the render and audio jobs, and every URL must already be this workspace's media.sume.com audio or video. Plan first with the unbilled endpoint.

Hosted MCP has timeline_audio and timeline_create; the flow is the tool, then jobs_wait, then the result tool. Details are in the Timeline audio docs and Timeline 1.0 docs.