API v1 Reference

Overview

VideoLingo API v1 lets a Pro account create YouTube translation tasks and monitor them from server-side code. API tasks use the same processing pipeline, balance, billing rules, and dashboard task list as tasks created on the website. Their default name starts with API ·.

API v1 currently accepts YouTube URLs only. It does not yet provide list, cancel, or webhook endpoints. Responses include Cache-Control: no-store and no CORS headers. Call the API from your server, not browser code; this also keeps your API key out of the client.

Get an API key

Sign in and open Dashboard → Account → API, or choose API Key from the avatar menu. An active Pro account receives one key beginning with vl_live_. You can reveal, copy, or regenerate it on that page.

For the examples below:

export VL_API_KEY="vl_live_replace_with_your_key"

Authentication

Send this header with every request:

Authorization: Bearer vl_live_xxxxxxxxxxxxxxxx

Cookies and query-string keys are ignored. A missing, malformed, regenerated, or unknown key returns 401 invalid_api_key. A valid key without an active Pro subscription returns 403 subscription_inactive.

Create a task

POST /tasks

Request headers

Idempotent retries

Use a new Idempotency-Key for each new video task. If a timeout or 5xx leaves the result uncertain, retry with the same key and exactly the same JSON body. Replays resolve to the same task and do not create a second charge once that task has started.

• A key belonging to a deleted task returns 422 invalid_request; use a new key.
• A key outside 8–128 characters returns 422 invalid_request.
• Do not reuse a key for different input or settings. API v1 does not promise payload-conflict detection for every pre-dispatch state.
• Without a key, every retry can create a separate task and charge.

Request body

Send one flat JSON object. Only youtube_url is required. Unknown fields are rejected, including server-controlled fields such as user_plan, watermark, prod, and model names.

target_language values

Use one of these exact values:

source_language values

Use one of these exact values:

Dubbing voice values

When dubbing is true, either omit tts_method to use the first preset for the selected target language, choose one matching fish_voice_<model-id> value below, or use fish_clone to clone the video's extracted reference voice.

The preset and target_language must come from the same row group. A French voice with target_language: "日本語", an unknown model id, or a retired value such as openai_tts is rejected with 422 invalid_request.

Minimal subtitle-only example

curl --request POST 'https://videolingo.io/api/v1/tasks' \
  --header "Authorization: Bearer $VL_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-8fa1a2b3' \
  --data '{
    "youtube_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "source_language": "en",
    "target_language": "简体中文",
    "dubbing": false
  }'

Dubbed example with an explicit voice

curl --request POST 'https://videolingo.io/api/v1/tasks' \
  --header "Authorization: Bearer $VL_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-4c5d6e7f' \
  --data '{
    "youtube_url": "https://youtu.be/dQw4w9WgXcQ",
    "name": "Japanese dubbed launch video",
    "source_language": "en",
    "target_language": "日本語",
    "dubbing": true,
    "tts_method": "fish_voice_b2d9d8db057042688a5e318b8f405bc2",
    "target_height": "1080",
    "demucs": true,
    "glossary": "VideoLingo: keep the product name in Latin characters"
  }'

What happens before acceptance

1. The API authenticates the key and validates the entire JSON body. Unknown or mismatched values fail before processing.
2. It reads the public video's duration. This check can take up to about 20 seconds. An inaccessible/private video returns 422 duration_unavailable; a video longer than 4 hours returns 422 invalid_request.
3. It checks the shared concurrency limit and available balance, reserves the task cost, and dispatches processing.

Success returns 202 Accepted and the task object. Its initial status is normally queued or processing.

Get a task

GET /tasks/{id}

Use the UUID returned by POST /tasks:

curl 'https://videolingo.io/api/v1/tasks/TASK_ID' \
  --header "Authorization: Bearer $VL_API_KEY"

The same endpoint can read a task created on the website if it belongs to the authenticated account. An invalid UUID, unknown task, deleted task, or another user's task returns the same 404 not_found response so task ownership is not disclosed.

Poll every 15–30 seconds until status is completed, failed, or cancelled. A read of an in-flight task also refreshes its latest processing state.

Task object

Both successful endpoints return the same shape:

{
  "id": "3f2c7a1e-5b8d-4c6f-9a0b-1d2e3f4a5b6c",
  "name": "API · dQw4w9WgXcQ",
  "status": "processing",
  "youtube_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "video_duration_seconds": 212,
  "cost_usd": 0.294444,
  "step": "Translating text",
  "step_index": 6,
  "error": null,
  "result": null,
  "created_at": "2026-09-24T08:00:00.000Z",
  "updated_at": "2026-09-24T08:03:12.000Z"
}

status values

step and step_index

Older dubbed tasks may briefly report the previously used stage 9. For display, prefer the accompanying step text when it is present.

result

On completion, result contains four direct-download URLs:

{
  "result": {
    "video": "https://cloud.videolingo.io/tasks/3f2c7a1e-…/output.mp4",
    "subtitles_zip": "https://cloud.videolingo.io/tasks/3f2c7a1e-…/srt.zip",
    "translated_srt": "https://cloud.videolingo.io/tasks/3f2c7a1e-…/trans.srt",
    "source_srt": "https://cloud.videolingo.io/tasks/3f2c7a1e-…/src.srt"
  }
}

Download URLs are task artifacts, not a completion signal by themselves. Wait for status: "completed" before using them.

Errors and retry behavior

HTTP errors always use this envelope. Branch on error.code; error.message is explanatory text and may change.

{
  "error": {
    "code": "concurrency_limit",
    "message": "At most 3 tasks can be queued or processing at once",
    "active": 3,
    "limit": 3
  }
}

Suggested transient-error backoff: 2 s, 5 s, 10 s, 30 s, then stop and surface the error. Honor a future Retry-After header if present. Do not automatically retry 401, 403, 404, or general 422 errors without first changing the underlying condition.

Limits and billing

• Concurrency: at most 3 tasks can be queued or processing for one account. Tasks started on the website count toward the same limit.
• Duration: one video can be at most 4 hours (14400 seconds).
• Billing: subtitle translation and dubbing use the same video-duration rate of USD 5 per hour. The resulting cost_usd is reserved from account balance when processing starts.
• Polling: there is currently no per-minute request quota, but poll responsibly every 15–30 seconds. Increase the interval for long videos and stop on a terminal status.
• Task creation: 202 Accepted means processing was accepted, not completed. Billing and artifacts belong to that asynchronous task.

Complete polling example

This Bash example requires curl and jq. It preserves the idempotency key, fails on API errors, and stops only on a terminal task status.

#!/usr/bin/env bash
set -euo pipefail
 
: "${VL_API_KEY:?Set VL_API_KEY first}"
API='https://videolingo.io/api/v1'
IDEMPOTENCY_KEY="video-$(date +%s)-$$"
 
RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST "$API/tasks" \
  --header "Authorization: Bearer $VL_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{
    "youtube_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "source_language": "en",
    "target_language": "简体中文",
    "dubbing": false
  }')
 
TASK_ID=$(jq --raw-output '.id // empty' <<<"$RESPONSE")
test -n "$TASK_ID" || { printf 'No task id: %s\n' "$RESPONSE" >&2; exit 1; }
printf 'Task: %s\n' "$TASK_ID"
 
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "$API/tasks/$TASK_ID" \
    --header "Authorization: Bearer $VL_API_KEY")
  STATUS=$(jq --raw-output '.status' <<<"$RESPONSE")
  STEP=$(jq --raw-output '.step // ""' <<<"$RESPONSE")
  printf '%s %s\n' "$STATUS" "$STEP"
 
  case "$STATUS" in
    completed) jq '.result' <<<"$RESPONSE"; break ;;
    failed|cancelled) jq '{status, error}' <<<"$RESPONSE" >&2; exit 1 ;;
    queued|processing|draft) sleep 30 ;;
    *) printf 'Unknown status: %s\n' "$STATUS" >&2; exit 1 ;;
  esac
done

Rotate an API key

• Choose Regenerate key on Dashboard → Account → API.
• The old key stops working immediately and returns 401; running tasks are not interrupted.
• Update every server, CI secret, and integration that uses the key before removing your saved copy.
• Regenerate immediately if exposure is suspected. Each account has only one active key at a time.
• When Pro expires the key returns 403. Renewing reactivates the same key, so routine subscription renewal does not require rotation.