tasks

Transcribe task

Submit a media URL for transcription. Runs asynchronously — the task is accepted with 202 and moves through queued → processing → a terminal status; poll GET /v1/tasks/{task_id} or pass wait there to long-poll. Supports word-level timestamps and speaker diarisation.

post/v1/tasks/transcribe

Request

  • Base URL: https://api.framelane.io
  • URL: https://api.framelane.io/v1/tasks/transcribe
  • Auth: HTTP bearer

Headers

Idempotency-Keystring nullable

Request body

metadataobject

Arbitrary key-value pairs echoed back in all webhook payloads.

webhook_urlstring uri nullable

Per-request webhook URL. Overrides workspace-level webhooks for this job only. Receives task.completed, task.failed, and progress events.

source_urlstring uri required
languagestring nullable

BCP-47 language code (e.g. 'en'). Auto-detected when omitted.

speech_model'universal-2' | 'universal-3-pro' | 'nano'

AssemblyAI speech model to use.

word_timingsboolean

Include word-level timestamps in the output.

speaker_labelsboolean

Enable speaker diarisation (who spoke when).

speakers_expectedinteger nullable

Hint for the expected number of speakers (used when speaker_labels=true).

sentiment_analysisboolean

Detect positive / neutral / negative sentiment per sentence.

entity_detectionboolean

Identify named entities (people, organisations, places, etc.).

auto_highlightsboolean

Extract the most important phrases automatically.

content_safetyboolean

Flag sensitive content categories.

iab_categoriesboolean

Classify content into IAB taxonomy topics.

word_booststring[]

Domain-specific terms to boost recognition accuracy (max 200).

Example request

{
  "metadata": {
    "project_id": "proj_123"
  },
  "webhook_url": "https://app.example.com/hooks/framelane"
}

Response

Idempotent replay.

idstring required

Unique job ID. Prefix indicates type: render_ or task_.

kind'render' | 'task' required
is_previewboolean

True for a cheap preview render. Previews are not billed and are excluded from the renders list.

editor_urlstring nullable

Open the project this job was submitted from in the authenticated console. Absent for a job with no project.

task_type'transcribe'

The AI task types the API offers.

Values:

  • transcribe — Speech-to-text transcription (via AssemblyAI) with optional analysis. Returns the transcript inline on the task's result object — there is no file artifact, so output is null and /v1/tasks/{id}/download returns 404.
workspace_idstring required

ID of the workspace that owns this job.

status'ingesting' | 'queued' | 'processing' | 'completed' | 'failed' | 'cancelled' required

Values:

  • ingesting — External source files are being probed for duration before the render is queued.
  • queued — Accepted and waiting for a worker to pick it up.
  • processing — Actively rendering or processing.
  • completed — Finished successfully; the output artifact is available.
  • failed — Terminated with an error (see error).
  • cancelled — Cancelled by the caller before completion.
progress_percentinteger

0–100 progress indicator updated by the render engine.

progress_stage'downloading' | 'compositing' | 'encoding' | 'uploading'

Values:

  • downloading — Fetching source media.
  • compositing — Compositing the scene on the GPU.
  • encoding — Encoding the output video.
  • uploading — Uploading the finished artifact to storage.
resultobject nullable

Structured JSON result for tasks that return data rather than a file — transcribe returns the transcript here (text, words, utterances, and any requested analysis). Populated once status == completed; null for renders and for any job whose only artifact is the file at output.url.

metadataobject

Caller-supplied key-value pairs echoed back on every webhook and response.

created_atstring date-time required

ISO-8601 UTC timestamp when the job was created.

updated_atstring date-time required

ISO-8601 UTC timestamp of the last status change.

completed_atstring date-time nullable

ISO-8601 UTC timestamp when the job reached a terminal state.

Example response

{
  "id": "render_01J8QR2K5VKDGN2T4FBM3CZYX7",
  "workspace_id": "ws_01J8QR2K5VKDGN2T4FBM3CZYX8",
  "output": {
    "url": "https://cdn-user.framelane.io/render_01J.../output.mp4",
    "width": 1920,
    "height": 1080,
    "duration": 15.3,
    "size_bytes": 12582912
  },
  "result": {
    "language_code": "en",
    "text": "Welcome back to the show."
  },
  "error": {
    "message": "Source URL returned 404."
  },
  "metadata": {
    "project_id": "proj_123",
    "user_ref": "usr_abc"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.