Skip to main content
POST
Auto-dub follows as a dub job; localization runs dub, lip-sync and on-screen as one job instead, checked as in createLocalization except what needs a transcript. When to use: when the media is ready and estimateProject is eligible. Side effects: Creates the project and job. Cost: 1 project credit now (0 when unlimited; refunds: Job.error); later minutes never above expected_cost_minutes; a balance below the auto-dub estimate answers 402. Text stays closed until a dub is charged (dub_payment_required). Async: returns 202 and a project_processing Job (Location); wait with getJob wait_seconds=20 (poll hint 10 s); typically 5 min (p95 30 min). Idempotency: Idempotency-Key required; a same-key retry within 24 h returns the job. Plan: free_dubbing -> free_languages; glossary_id; translation_instructions; subtitles -> subtitle_import; auto_dub; onscreen; localization (conditional). Required scopes: projects:write, credits:spend; localization adds its stages’ (conditional) Errors: media_not_found (404), folder_not_found (404), glossary_not_found (404), media_not_ready (409), media_processing_failed (422), unsupported_media_type (415), media_too_large (413), media_too_long (413), feature_not_in_plan (403), prepare_mode_not_enabled (403), feature_temporarily_disabled (503), plan_configuration_error (500), source_language_not_supported (422), target_language_not_supported (422), glossary_language_mismatch (422), subtitles_invalid (422), auto_dub_required (422), voice_not_in_pool (422), instant_clone_not_available (422), onscreen_language_not_supported (422), localization_combination_not_supported (422), onscreen_video_too_long (422), cost_changed (409), insufficient_balance (402), too_many_concurrent_jobs (429)

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

​
projects:write
​
credits:spend

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]+$

Body

application/json

Body of createProject (<= 5 MiB).

​
media_id
string
required

A ready media item of this workspace (from completeUpload or importMedia).

Maximum string length: 64
​
target_language
string
required

Target language code (GET /v3/languages?capability=translation).

Maximum string length: 32
​
free_dubbing
boolean
default:false

Use the free dubbing variant (entitlement free_languages).

​
source_language
string

Source language code; omit to auto-detect. Required with subtitles.source.

Maximum string length: 32
​
name
string

Project name; defaults to the media file name. Not de-duplicated.

Required string length: 1 - 255
​
num_speakers
integer<int32>

Number of speakers; omit to detect (or derive from subtitle labels).

Required range: 1 <= x <= 20
​
folder_id
string

Folder to create the project in; omit for the root.

Maximum string length: 64
​
glossary_id
string

Glossary to apply (entitlement glossary); its language pair must match.

Maximum string length: 64
​
translation_instructions
string

Instructions for the translator (entitlement translation_instructions); forces LLM translation.

Maximum string length: 8192
​
dubbing_model
enum<string>

Requested dubbing model; omitted = v2. A named model is stored on the project (requested_dubbing_model); the effective model may differ (dubbing_model_override_reason).

Available options:
v1,
v2
​
subtitles
object

Subtitles to import instead of transcribing (entitlement subtitle_import). Source and target must have equal cue counts and timings; source_language is required with source.

​
auto_dub
boolean
default:true

Dub automatically after translation (default); the project's text stays closed until a dub is charged (409 dub_payment_required). Needs an active subscription or a trial; a lapsed subscription answers 403 feature_not_in_plan. false answers 403 prepare_mode_not_enabled unless preparation is enabled; a trial payer must keep it true (422 auto_dub_required).

​
speaker_voices
object[]

Voices to apply before the first dub. Availability and entitlement are checked up front (422 voice_not_in_pool, instant_clone_not_available; an instant clone needs the entitlement instant_voice_clone); a duplicate speaker_label answers 422 validation_failed. If a clone cannot be applied once speakers are known (too little speech, daily clone quota), the speaker keeps the suggested voice and the job result carries speaker_voice_not_applied with the label. Speakers without an entry get the suggested voice (Speaker.voice_origin).

Required array length: 1 - 20 elements
​
onscreen
object

On-screen auto-start.

​
localization
object

Run dub, lip-sync and on-screen as one localization job after translation.

​
expected_cost_minutes
integer<int32>

Cap for the deferred spends (auto-dub after translation, on-screen auto-start after the first dub, the stages of a localization block). Required unless auto_dub: false is sent and nothing else defers a spend (422 validation_failed, errors[].code expected_cost_required). A deferred spend priced above the cap is skipped, uncharged. A cap below the current total fails 409 cost_changed at the request, and too few minutes for it fail 402 insufficient_balance; the skip applies only when the price or balance changes between the request and dispatch.

Required range: 0 <= x <= 100000
​
metadata
object

Client metadata: <= 20 string keys (<= 40 characters) and values (<= 500). Returned on reads, never sent in webhooks.

Response

Accepted: Job.

Asynchronous work started through v3, and automatic follow-up work (auto-dub, on-screen auto-start, the stages of a localization run) on projects created through v3. Started by 202 responses (Location: /v3/jobs/{id}); wait with getJob wait_seconds. Finished jobs can be read for 90 days, then answer 404 job_not_found. Work started in the web app or API v2 has no job.

​
object
enum<string>
required

Always job.

Available options:
job
​
id
string
required

Job id.

​
workspace_id
string
required

Workspace that owns the job (and whose owner pays).

​
type
enum<string>
required

Job type. Open enum: new types are added over time.

  • media_import: registering uploaded or imported media (poll hint 3 s; cancelable)
  • project_processing: the project pipeline up to translation (poll hint 10 s)
  • translation: retranslating segments (poll hint 5 s)
  • segment_generation: paid voicing of chosen segments into downloadable clips (poll hint 5 s)
  • dub: dubbing or redubbing (poll hint 10 s)
  • lipsync: lip-sync (poll hint 30 s)
  • onscreen: on-screen text translation (poll hint 15 s; cancelable while queued)
  • localization: dub, lip-sync and on-screen as one run with child jobs (poll hint 15 s)
  • voice_clone: creating a voice clone (poll hint 10 s)
  • export: rendering an export (poll hint 15 s)
  • file_restore: restoring archived files (poll hint 300 s)
Available options:
media_import,
project_processing,
translation,
segment_generation,
dub,
lipsync,
onscreen,
localization,
voice_clone,
export,
file_restore
​
status
enum<string>
required

Job status. Monotonic: never goes backwards and never leaves a terminal state.

  • queued: accepted, not started
  • running: in progress
  • succeeded: finished; see result
  • failed: finished; see error
  • canceled: canceled, or its project was deleted (error.code = project_deleted)
Available options:
queued,
running,
succeeded,
failed,
canceled
​
progress
integer<int32> | null
required

0-100; null when the type has no honest progress.

Required range: 0 <= x <= 100
​
stage
enum<string> | null
required

Per-type stage; for a localization job, the running stage's.

Available options:
queued,
uploading,
transcribing,
separating_audio,
detecting_speakers,
matching_voices,
translating,
voicing,
merging,
downloading,
extracting_audio,
face_check,
waiting_for_worker,
rendering,
charging,
waiting_for_runner,
starting,
preparing,
checking,
publishing,
cloning,
restoring
​
queue_position
integer<int32> | null
required

Queue position (1 = next).

​
estimated_finish_at
string<date-time> | null
required

Estimated completion from the queue position and the type's typical duration (on-screen: the runner's ETA); null when terminal or unknown. An estimate, not a deadline.

​
overdue
boolean
required

True once the job runs past its type's overdue threshold: Rask is alerted. Keep waiting or check back later; do not start the same work again.

​
project_id
string | null
required

Project.

​
media_id
string | null
required

Media.

​
parent_job_id
string | null
required

The job that started this system job: the project_processing job of an auto-dub, the dub whose merge started an on-screen auto-start, the localization job of a stage, the project_processing job of a localization block, or the failed run a resumed localization job continues.

​
channel
enum<string>
required

Who started a job.

  • api: REST API v3
  • mcp: the Rask MCP server
  • system: automatic (auto-dub, on-screen auto-start, the stages of a localization run)
Available options:
api,
mcp,
system
​
params
object
required

Normalized request echo: a union on type (= Job.type).

​
details
object | null
required

Live per-type state.

​
stages
object[] | null
required

The stages of a localization job in run order; null for other types.

​
cost
object
required

Quoted at creation; charged turns true once the charge is committed. A localization job has no charge of its own: minutes is the sum of its stages charged and not refunded so far, charged is true once any stage is charged, refunded is true only when every charged stage was refunded, refunded_at is the latest refund. stages[].cost holds each stage; the quote is params.expected_cost_minutes.

​
result
object
required

Set when succeeded; a failed segment_generation job may also list clips already voiced.

​
error
object | null
required

Set when failed; on a canceled job only for the cancellation reason project_deleted (the project was deleted while the job ran; its work is discarded, refunded only for on-screen); instance is /v3/jobs/{id}, detail is generic. Each code's status, retry, recommendation and hint are in components.x-rask-job-errors. Codes by type: media_import source_download_failed, unsupported_media_type, media_corrupt, media_processing_failed, media_too_large (a voice sample above its limit); project_processing media_processing_failed, source_unavailable, no_audio_track, transcription_failed, no_speech_detected, audio_separation_failed, speaker_detection_failed, translation_failed, subtitle_import_rolled_back, project_processing_timeout, internal_error; translation translation_failed, translation_dispatch_failed, translation_timeout; segment_generation (cause_code) segment_generation_failed, segment_generation_timeout; localization localization_stage_failed, localization_stage_skipped (failed_stage, cause_code); dub (cause_code) dub_voiceover_failed, dub_merge_failed, dub_failed, dub_timeout; lipsync lipsync_failed, face_check_failed, no_face_detected, lipsync_rejected (cause_code), lipsync_timeout; onscreen onscreen_queue_timeout, onscreen_runner_lost, onscreen_runner_failed, onscreen_provider_unavailable, onscreen_finalize_timeout, onscreen_invalid_result, onscreen_publish_failed, onscreen_source_unavailable, onscreen_charge_failed; voice_clone voice_clone_failed, voice_clone_timeout; export export_failed; file_restore restore_failed. A failed job refunds its minutes (onscreen_charge_failed never charged). A failed localization job refunds only the failed stage, by its type's rule: succeeded stages stay charged, and skipped or unreached stages were never charged. A failed project_processing job refunds its project credit when a stage from transcription to translation failed, when it timed out and when a copy failed, but not for media_processing_failed, source_unavailable, no_audio_track or the internal_error of a new project.

​
created_at
string<date-time>
required

Creation time.

​
started_at
string<date-time> | null
required

Start time.

​
finished_at
string<date-time> | null
required

End time.

​
links
object
required

Path-absolute API links.