Skip to main content
POST
/
v1
/
tasks
/
transcribe
Transcribe task
curl --request POST \
  --url https://api.framelane.io/v1/tasks/transcribe \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "source_url": "<string>",
  "metadata": {
    "project_id": "proj_123"
  },
  "webhook_url": "https://app.example.com/hooks/framelane",
  "language": "<string>",
  "speech_model": "universal-2",
  "word_timings": true,
  "speaker_labels": false,
  "speakers_expected": 5,
  "sentiment_analysis": false,
  "entity_detection": false,
  "auto_highlights": false,
  "content_safety": false,
  "iab_categories": false,
  "word_boost": [
    "<string>"
  ]
}
'
{
  "id": "render_01J8QR2K5VKDGN2T4FBM3CZYX7",
  "kind": "render",
  "workspace_id": "ws_01J8QR2K5VKDGN2T4FBM3CZYX8",
  "status": "queued",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "task_type": "transcribe",
  "progress_percent": 0,
  "progress_stage": "compositing",
  "output": {
    "url": "https://cdn-user.framelane.io/render_01J.../output.mp4",
    "width": 1920,
    "height": 1080,
    "duration": 15.3,
    "size_bytes": 12582912
  },
  "error": {
    "code": "invalid_source",
    "message": "Source URL returned 404."
  },
  "metadata": {
    "project_id": "proj_123",
    "user_ref": "usr_abc"
  },
  "completed_at": "2023-11-07T05:31:56Z"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Idempotency-Key
string | null

Body

application/json
​
source_url
string<uri>
required
Required string length: 1 - 2083
​
metadata
Metadata · object

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

Example:
{ "project_id": "proj_123" }
​
webhook_url
string<uri> | null

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

Required string length: 1 - 2083
Example:

"https://app.example.com/hooks/framelane"

​
language
string | null

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

​
speech_model
enum<string>
default:universal-2

AssemblyAI speech model to use.

Available options:
universal-2,
universal-3-pro,
nano
​
word_timings
boolean
default:true

Include word-level timestamps in the output.

​
speaker_labels
boolean
default:false

Enable speaker diarisation (who spoke when).

​
speakers_expected
integer | null

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

Required range: 1 <= x <= 10
​
sentiment_analysis
boolean
default:false

Detect positive / neutral / negative sentiment per sentence.

​
entity_detection
boolean
default:false

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

​
auto_highlights
boolean
default:false

Extract the most important phrases automatically.

​
content_safety
boolean
default:false

Flag sensitive content categories.

​
iab_categories
boolean
default:false

Classify content into IAB taxonomy topics.

​
word_boost
string[]

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

Response

Idempotent replay.

A render job or AI task.

​
id
string
required

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

Example:

"render_01J8QR2K5VKDGN2T4FBM3CZYX7"

​
kind
enum<string>
required

Whether this is a render or a task.

Available options:
render,
task
Example:

"render"

​
workspace_id
string
required

ID of the workspace that owns this job.

Example:

"ws_01J8QR2K5VKDGN2T4FBM3CZYX8"

​
status
enum<string>
required

Current lifecycle state: queued → processing → completed / failed / cancelled.

Available options:
ingesting,
queued,
processing,
completed,
failed,
cancelled
Example:

"queued"

​
created_at
string<date-time>
required

ISO-8601 UTC timestamp when the job was created.

​
updated_at
string<date-time>
required

ISO-8601 UTC timestamp of the last status change.

​
task_type
enum<string> | null

For task jobs only — the specific AI operation.

Available options:
remove_background,
gaze_redirect,
super_resolution,
transcribe
Example:

"transcribe"

​
progress_percent
integer
default:0

0–100 progress indicator updated by the render engine.

Required range: 0 <= x <= 100
Example:

0

​
progress_stage
enum<string> | null

Current processing phase within a job.

Available options:
downloading,
compositing,
encoding,
uploading
Example:

"compositing"

​
output
JobOutput · object

Populated once status == completed. Contains the signed artifact URL.

​
error
JobError · object

Populated when status == failed. Contains a structured error code.

​
metadata
Metadata · object

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

Example:
{
  "project_id": "proj_123",
  "user_ref": "usr_abc"
}
​
completed_at
string<date-time> | null

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