Create job

Order captions

POST https://api.el.ai/v1/jobs

Requires full key access. Exactly one source is required. Default maximum media length: 12 hours, configurable per workspace. A lower workspace-wide media limit still applies.

Triggers POST Job outcome

Authorization

Authorization header · string Required

Bearer el_live_…, a workspace API key. This endpoint needs a key with full access. About keys

Headers

Idempotency-Key string

Optional. Use a unique key per order and reuse it with the same body to retry safely. Keys are scoped to the workspace. A replay returns the original job with 200 and idempotent-replayed: true. Reusing a key with a different body returns 409 idempotency_conflict. Without a key, each accepted request creates a new job and charge.

1–255 chars
matches ^[!-~]+$

Request body

application/json

Provide exactly one source: media_url OR upload_id. Sending both or neither is invalid. Choose the Media URL or Uploaded file variant below.

Send exactly one of: Media URL (media_url) or Uploaded file (upload_id)

media_url string

Public HTTP(S) video/audio URL, including supported YouTube links. Required only for the Media URL variant; omit when using upload_id.

≥ 1 chars
upload_id string · uuid

ID returned by POST /uploads, after uploading the file. Required only for the Uploaded file variant; omit when using media_url.
title string

Dashboard title and download filename. Defaults to the generated job ID. Default maximum: 300 characters, configurable per workspace.

≥ 1 chars
style string

clean removes fillers, false starts, and stutters; verbatim keeps every spoken word.

One of

clean
verbatim

Default

clean
model string

Captioning model. Only ave-base is supported.

One of

ave-base

Default

ave-base
speaker_labels boolean

Identify speaker turns. Set false for dialogue without labels.

Default

true
speaker_label_style string

SRT/VTT labels: >> NAME:, [NAME], NAME:, or dashes without names. Ignored when speaker_labels is false. Transcripts use their native speaker headings; JSON has a separate speaker field.

One of

gt_name
brackets
colon
dashes

Default

gt_name
atmospherics boolean

Include meaningful non-speech sounds. Uses the same add-on pricing as dashboard checkout.

Default

true
profanity string

Keep profanity, mask it (f***), replace it with [expletive], or omit it. Does not alter source audio.

One of

as_spoken
mask
label
omit

Default

as_spoken
redactions Redactions

Privacy controls for caption text, using the same redaction pricing as checkout. Source audio and video are unchanged.
Accepts one of:
- Standard replacement
- Custom replacement requires replacement, custom_replacement
- pii boolean
  
  Redact personal data such as emails and phone numbers.
  
  Default
  
  false
- names boolean
  
  Redact named individuals.
  
  Default
  
  false
- organizations boolean
  
  Redact organization names.
  
  Default
  
  false
- terms array of string
  
  Custom terms to redact, one term per item; each must be a nonblank single line.
  
  Default
  
  []
  
  ≤ 200 items
- replacement string
  
  Replace with [REDACTED], a category such as [EMAIL], nothing, or custom_replacement.
  
  One of
  
  redacted
  category_label
  silent
  custom_string
  
  Default
  
  category_label
- custom_replacement string
  
  Required when replacement is custom_string. Nonblank, single-line text.
  
  1–120 chars
glossary array of string

Names and terms with preferred spelling, used where the audio supports them. Defaults to at most 200 terms of 100 characters each; configurable per workspace.

Default

[]
webhook_url string · uri

Public HTTPS callback. Redirects are not followed.

≤ 2048 chars
matches ^https://
metadata map of string

Your string key–value pairs, returned on the job and in webhook events. Defaults: 20 keys of 1–40 characters, values up to 500 characters. These maxima are configurable per workspace.

Response · 200

application/json

Idempotent replay.

id string · uuid
object string

One of

job
status string

One of

queued
processing
completed
cancelled
progress integer · nullable

0–100
eta string · date-time · nullable
title string
media object
- type string
  
  One of
  
  url
  upload
- url string · nullable
- upload_id string · uuid · nullable
- duration_seconds number
language string · nullable
options object
- style string
  
  clean removes fillers, false starts, and stutters; verbatim keeps every spoken word.
  
  One of
  
  clean
  verbatim
  
  Default
  
  clean
- model string
  
  Captioning model. Only ave-base is supported.
  
  One of
  
  ave-base
  
  Default
  
  ave-base
- speaker_labels boolean
  
  Identify speaker turns. Set false for dialogue without labels.
  
  Default
  
  true
- speaker_label_style string
  
  SRT/VTT labels: >> NAME:, [NAME], NAME:, or dashes without names. Ignored when speaker_labels is false. Transcripts use their native speaker headings; JSON has a separate speaker field.
  
  One of
  
  gt_name
  brackets
  colon
  dashes
  
  Default
  
  gt_name
- atmospherics boolean
  
  Include meaningful non-speech sounds. Uses the same add-on pricing as dashboard checkout.
  
  Default
  
  true
- profanity string
  
  Keep profanity, mask it (f***), replace it with [expletive], or omit it. Does not alter source audio.
  
  One of
  
  as_spoken
  mask
  label
  omit
  
  Default
  
  as_spoken
- redactions Redactions
  
  Privacy controls for caption text, using the same redaction pricing as checkout. Source audio and video are unchanged.
  Accepts one of:
  Standard replacement
  Custom replacement requires replacement, custom_replacement
  pii boolean
  
  Redact personal data such as emails and phone numbers.
  
  Default
  
  false
  
  names boolean
  
  Redact named individuals.
  
  Default
  
  false
  
  organizations boolean
  
  Redact organization names.
  
  Default
  
  false
  
  terms array of string
  
  Custom terms to redact, one term per item; each must be a nonblank single line.
  
  Default
  
  []
  
  ≤ 200 items
  
  replacement string
  
  Replace with [REDACTED], a category such as [EMAIL], nothing, or custom_replacement.
  
  One of
  
  redacted
  category_label
  silent
  custom_string
  
  Default
  
  category_label
  
  custom_replacement string
  
  Required when replacement is custom_string. Nonblank, single-line text.
  
  1–120 chars
- glossary array of string
- webhook_url string · nullable
cost object · nullable
- amount string
  
  Decimal amount in USD, net of refunds.
- currency string
  
  One of
  
  usd
cancellation object · nullable
- reason string
  
  One of
  
  unsupported_language
  unsupported_media
  unusable_media
  media_unavailable
  deleted
  not_started
- message string
captions object · nullable
- srt string · uri
- vtt string · uri
- txt string · uri
- docx string · uri
- json string · uri
metadata map of string

String values. Defaults: 20 keys of 1–40 characters, values up to 500 characters. These maxima are configurable per workspace.
created_at string · date-time
completed_at string · date-time · nullable

Headers

request-id string

Support request identifier.
cache-control string

One of

no-store
idempotent-replayed string

One of

true

Response · 201

application/json

Created; mediaOrder initialization completed.

id string · uuid
object string

One of

job
status string

One of

queued
processing
completed
cancelled
progress integer · nullable

0–100
eta string · date-time · nullable
title string
media object
- type string
  
  One of
  
  url
  upload
- url string · nullable
- upload_id string · uuid · nullable
- duration_seconds number
language string · nullable
options object
- style string
  
  clean removes fillers, false starts, and stutters; verbatim keeps every spoken word.
  
  One of
  
  clean
  verbatim
  
  Default
  
  clean
- model string
  
  Captioning model. Only ave-base is supported.
  
  One of
  
  ave-base
  
  Default
  
  ave-base
- speaker_labels boolean
  
  Identify speaker turns. Set false for dialogue without labels.
  
  Default
  
  true
- speaker_label_style string
  
  SRT/VTT labels: >> NAME:, [NAME], NAME:, or dashes without names. Ignored when speaker_labels is false. Transcripts use their native speaker headings; JSON has a separate speaker field.
  
  One of
  
  gt_name
  brackets
  colon
  dashes
  
  Default
  
  gt_name
- atmospherics boolean
  
  Include meaningful non-speech sounds. Uses the same add-on pricing as dashboard checkout.
  
  Default
  
  true
- profanity string
  
  Keep profanity, mask it (f***), replace it with [expletive], or omit it. Does not alter source audio.
  
  One of
  
  as_spoken
  mask
  label
  omit
  
  Default
  
  as_spoken
- redactions Redactions
  
  Privacy controls for caption text, using the same redaction pricing as checkout. Source audio and video are unchanged.
  Accepts one of:
  Standard replacement
  Custom replacement requires replacement, custom_replacement
  pii boolean
  
  Redact personal data such as emails and phone numbers.
  
  Default
  
  false
  
  names boolean
  
  Redact named individuals.
  
  Default
  
  false
  
  organizations boolean
  
  Redact organization names.
  
  Default
  
  false
  
  terms array of string
  
  Custom terms to redact, one term per item; each must be a nonblank single line.
  
  Default
  
  []
  
  ≤ 200 items
  
  replacement string
  
  Replace with [REDACTED], a category such as [EMAIL], nothing, or custom_replacement.
  
  One of
  
  redacted
  category_label
  silent
  custom_string
  
  Default
  
  category_label
  
  custom_replacement string
  
  Required when replacement is custom_string. Nonblank, single-line text.
  
  1–120 chars
- glossary array of string
- webhook_url string · nullable
cost object · nullable
- amount string
  
  Decimal amount in USD, net of refunds.
- currency string
  
  One of
  
  usd
cancellation object · nullable
- reason string
  
  One of
  
  unsupported_language
  unsupported_media
  unusable_media
  media_unavailable
  deleted
  not_started
- message string
captions object · nullable
- srt string · uri
- vtt string · uri
- txt string · uri
- docx string · uri
- json string · uri
metadata map of string

String values. Defaults: 20 keys of 1–40 characters, values up to 500 characters. These maxima are configurable per workspace.
created_at string · date-time
completed_at string · date-time · nullable

Headers

request-id string

Support request identifier.
cache-control string

One of

no-store

Errors

Errors share one shape: an error object with a stable code and a human-readable message. See Errors and retries.

400	Invalid request
401	Missing, invalid or revoked API key
402	Insufficient funds or budget
403	Key or workspace does not allow this operation
404	Resource not found in this workspace
409	Conflict
413	JSON body exceeds 64 KiB
415	Unsupported content type
422	Media or order cannot be processed
429	Shared read limit per API key or write limit per workspace exceeded
500	Internal error
503	temporarily_unavailable: request limit enforcement is unavailable, or job submission is busy. Retry after 5 seconds.

curl -X POST https://api.el.ai/v1/jobs \
  -H "Authorization: Bearer $ECHO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-lecture-04" \
  -d '{
    "media_url": "https://example.com/video.mp4"
  }'

import os
import requests

response = requests.post(
    "https://api.el.ai/v1/jobs",
    headers={
        "Authorization": f"Bearer {os.environ['ECHO_API_KEY']}",
        "Idempotency-Key": "order-lecture-04",
    },
    json={
        "media_url": "https://example.com/video.mp4",
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.el.ai/v1/jobs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ECHO_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "order-lecture-04",
  },
  body: JSON.stringify({
    "media_url": "https://example.com/video.mp4"
  }),
});
const data = await response.json();
console.log(data);

{
  "id": "cec18557-248a-4916-938a-4cb386bedcb9",
  "object": "job",
  "status": "queued",
  "progress": 62,
  "eta": "2026-09-25T20:33:37Z",
  "title": "Lecture 4: Consumer choice",
  "media": {
    "type": "url",
    "url": "https://example.com/video.mp4",
    "upload_id": "45cfe506-9a33-4f95-9a50-3a0e64c5b3e2",
    "duration_seconds": 2893.41
  },
  "language": "en",
  "options": {
    "style": "clean",
    "model": "ave-base",
    "speaker_labels": true,
    "speaker_label_style": "gt_name",
    "atmospherics": true,
    "profanity": "as_spoken",
    "redactions": {
      "pii": false,
      "names": false,
      "organizations": false,
      "terms": [
        "terms_value"
      ],
      "replacement": "redacted",
      "custom_replacement": "custom_replacement_value"
    },
    "glossary": [
      "Dr. Okafor"
    ],
    "webhook_url": "https://example.com/hooks/echo"
  },
  "cost": {
    "amount": "9.80",
    "currency": "usd"
  },
  "cancellation": {
    "reason": "unsupported_language",
    "message": "Send exactly one of media_url or upload_id."
  },
  "captions": {
    "srt": "https://example.com/srt",
    "vtt": "https://example.com/vtt",
    "txt": "https://example.com/txt",
    "docx": "https://example.com/docx",
    "json": "https://example.com/json"
  },
  "metadata": {
    "course": "ECON 101"
  },
  "created_at": "2026-09-25T20:33:37Z",
  "completed_at": "2026-09-25T20:33:37Z"
}

{
  "id": "cec18557-248a-4916-938a-4cb386bedcb9",
  "object": "job",
  "status": "queued",
  "progress": 62,
  "eta": "2026-09-25T20:33:37Z",
  "title": "Lecture 4: Consumer choice",
  "media": {
    "type": "url",
    "url": "https://example.com/video.mp4",
    "upload_id": "45cfe506-9a33-4f95-9a50-3a0e64c5b3e2",
    "duration_seconds": 2893.41
  },
  "language": "en",
  "options": {
    "style": "clean",
    "model": "ave-base",
    "speaker_labels": true,
    "speaker_label_style": "gt_name",
    "atmospherics": true,
    "profanity": "as_spoken",
    "redactions": {
      "pii": false,
      "names": false,
      "organizations": false,
      "terms": [
        "terms_value"
      ],
      "replacement": "redacted",
      "custom_replacement": "custom_replacement_value"
    },
    "glossary": [
      "Dr. Okafor"
    ],
    "webhook_url": "https://example.com/hooks/echo"
  },
  "cost": {
    "amount": "9.80",
    "currency": "usd"
  },
  "cancellation": {
    "reason": "unsupported_language",
    "message": "Send exactly one of media_url or upload_id."
  },
  "captions": {
    "srt": "https://example.com/srt",
    "vtt": "https://example.com/vtt",
    "txt": "https://example.com/txt",
    "docx": "https://example.com/docx",
    "json": "https://example.com/json"
  },
  "metadata": {
    "course": "ECON 101"
  },
  "created_at": "2026-09-25T20:33:37Z",
  "completed_at": "2026-09-25T20:33:37Z"
}

Error

{
  "error": {
    "code": "invalid_request",
    "message": "Send exactly one of media_url or upload_id.",
    "param": "media_url"
  }
}