Skip to main content
POST
Insert a segment
Source text without a translation starts a translation. An unknown speaker gets a suggested voice. When to use: to add missing speech. Side effects: Commits atomically: the project’s pipeline_status becomes transcript_edited, segment ETags change, affected segments become outdated (listed in the response’s effects) and their audio may be dropped. Cost: Free. An edit that starts a translation counts against the payer’s translation budget (429 rate_limited, policy translation-hour) and its 5 concurrent translation jobs (429 too_many_concurrent_jobs); then nothing is written. Idempotency: Idempotency-Key required (an insert has no ETag); a same-key retry within 24 h replays the first response (Idempotent-Replayed: true). Concurrency: no ETag. Refused during processing (409 project_not_ready) and while a dub runs, from its start until its merge ends or it fails (409 dub_in_progress); 409 transcript_busy means concurrent writes kept conflicting: retry after Retry-After. Paid text: on a project created through v3, 409 dub_payment_required until a dub of that project is charged. Required scopes: transcripts:write Errors: transcript_not_ready (409), project_not_ready (409), dub_in_progress (409), transcript_busy (409), too_many_concurrent_jobs (429), dub_payment_required (409)

Authorizations

Authorization
string
header
required

API key from Settings -> API keys, sent as Authorization: Bearer <key> (SDK environment variable RASK_API_KEY). Bound to one workspace and one acting user. Operations list the scopes they need (OpenAPI 3.1 scopes on a bearer scheme).

Scopes

transcripts:write

Headers

Idempotency-Key
string
required

Required. A unique key per logical request (SDKs send a bare UUIDv4; an RFC 9651 quoted string is accepted and unquoted); reuse it unchanged on retries. Kept 24 h per (workspace, acting user).

Required string length: 1 - 255
Pattern: ^[\x20-\x7E]+$

Path Parameters

project_id
string
required

Project id (from createProject or listProjects).

Maximum string length: 64

Body

application/json

Body of createSegment.

start_seconds
number<double>
required

Start in seconds (<= 3 decimals).

Required range: x >= 0
end_seconds
number<double>
required

End in seconds (<= 3 decimals).

Required range: x >= 0
speaker_id
string
required

Speaker (SPEAKER_NN).

Maximum string length: 11
Pattern: ^SPEAKER_\d{2,3}$
source_text
string

Source text; without a translation it is translated (<= 5000 characters; no control characters but newline).

Maximum string length: 5000
translation_text
string

Translation (<= 5000 characters; no control characters but newline).

Maximum string length: 5000
needs_attention
boolean

Review flag.

Response

Created: TranscriptEditResult.

Result of a segment or transcript mutation. Transient (no id).

object
enum<string>
required

Always transcript_edit_result.

Available options:
transcript_edit_result
segments
object[]
required

Every created or changed segment, read back consistently, in time order.

deleted_segment_ids
string[]
required

Deleted segments.

operations
object[]
required

Segments per operation.

effects
object
required

Effects of a committed write.

warnings
object[]
required

Warnings.