TTS sentence_ids: max 1,000 per request vs the 20,000-character cap

When you send a Sume TTS job by transcript_source, you select between 1 and 1,000 sentence ids. The character limit is still 20,000, so for normal prose the characters run out first: 1,000 sentences would only fit if they averaged 20 characters. The id limit matters mostly for lists of very short lines.

The two limits side by side

transcript_source takes a script_revision_id and sentence_ids. Each id is a bounded ASCII string up to 128 characters, drawn from letters, digits, underscore and hyphen. Ids must be unique and in source order. You send either transcript_source or a literal transcript, never both and never neither.

A worked case

A script of 400 sentences averaging 60 characters is 24,000 characters, so it exceeds 20,000 even though it is far below 1,000 ids. Split it into two selections of 200 sentences, about 12,000 characters each. A script of 1,200 menu items averaging 15 characters is 18,000 characters, under the character cap but over the id cap, so it also needs two requests. Pick the split by whichever limit you hit.

{
  "transcript_source": {
    "script_revision_id": "revision_from_source_manifest",
    "sentence_ids": ["s001", "s002", "s003"]
  },
  "avatar_handle": "speaker",
  "language": "en"
}

Handling the errors

Over-limit selections fail validation and never reserve credit or queue work, so a too-large request is a cheap mistake. Count before you send: sum the character counts from the manifest for your selected sentences, check they are at or under 20,000, and check the id count is at or under 1,000. If either is over, cut the selection at a sentence boundary and submit the rest as a second request.

Where to get the ids

Read them from GET /v1/tts-1.0/source in the authenticated thread. The manifest gives opaque sentence ids, indexes, character counts and a source hash, so you do not copy script text into the request. Duplicate, unknown or reordered ids are errors and never reserve credit.