Get started with the alugha API

Summary

The alugha API lets you programmatically create videos, read tracks, and manage assets on alugha — so you can integrate multilingual video into your own tech stack. The API follows the OpenAPI 3.1 standard, uses Bearer token authentication, and is available on the Enterprise plan as an add-on.

Prerequisites

Before you begin:

An alugha account with API access enabled (included with Enterprise, available as an add-on on paid plans – contact sales).
Command-line familiarity (or any HTTP client, SDK, or automation tool of your choice).
Enough credits in your wallet if you plan to trigger AI actions via the API – API calls that create videos or run AI consume the same credits as the dubbr.

Base URL and authentication

All API requests go to the base URL:

https://alugha.com/v2

Authentication uses Bearer tokens. Generate an API token from your account’s API settings page, then pass it as the Authorization header on every request:

Authorization: Bearer YOUR_API_TOKEN

When creating a token, select the scopes (permissions) the token needs. Requests without sufficient scopes return 403 Forbidden.

Your first API call

Read an asset by ID. Replace __ID__ with an actual asset UUID and YOUR_API_TOKEN with your token:

curl --request GET \
  --url https://alugha.com/v2/assets/__ID__ \
  --header "Authorization: Bearer YOUR_API_TOKEN"

A successful response looks like this:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "created": "2026-04-16T08:55:34.342Z",
  "modified": "2026-04-16T08:55:34.342Z",
  "type": "video",
  "ownerId": "123e4567-e89b-12d3-a456-426614174000"
}

Core resources: Assets, Tracks, Videos

The API has three main resource types that mirror the alugha data model:

Assets — abstract files. An image asset can contain multiple image files at different resolutions; a video asset contains video files, thumbnails, and audio files. These files are called representations.
Tracks — language-specific content of a video. Each language gets its own track with its own title, description, tags, and subtitle/dubbing segments.
Videos — the main resource. A video groups one or more assets with one or more tracks (the multilingual layer).

Asset endpoints

GET /assets/{id} — read an asset by ID (returns id, type, ownerId, timestamps).

Track endpoints

GET /tracks — list tracks of a video.
GET /tracks/{id} — read a track by ID.

Video endpoints

POST /videos — create a new video.
GET /videos/{id} — read a video by ID.

Creating a video

Send a POST /videos request with the default-track metadata and optionally a downloadFromUrl pointer. alugha will fetch the file from that URL and start processing.

curl --request POST \
  --url https://alugha.com/v2/videos \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "defaultTrack": {
      "langCode": "eng",
      "title": "My first API-created video",
      "description": "Uploaded via the alugha API."
    },
    "downloadFromUrl": "https://example.com/my-video.mp4",
    "statusWebhook": "https://my-app.com/alugha-status"
  }'

Language codes (langCode)

alugha uses ISO 639-3 (three-letter) language codes, optionally followed by a two-letter ISO 3166-1 country code or a three-digit UN M.49 region code:

German → deu
American English → eng-us
Latin American Spanish → spa-419

downloadFromUrl

The URL must be publicly accessible as-is — alugha does not pass any authentication headers when fetching. For private or protected URLs, use presigned URLs with expiring signatures from your storage provider (S3, GCS, Azure Blob, etc.).

statusWebhook

Optional callback URL that alugha invokes whenever the video’s processing status changes. You will receive multiple calls during the lifecycle:

Download of the source file finished
Encoding started
Video ready for playback

Use the webhook to keep your own system in sync — for example, to mark a content row as ready once processing completes.

Common response codes

200 — Success.
401 Unauthorized — no Bearer token was provided, or the token is invalid. Generate a new token from your API settings.
403 Forbidden — the token is valid but lacks the required scopes for this operation. Regenerate the token with the correct scopes.
404 Not Found — the requested resource does not exist. Double-check the ID; contact support if the resource should exist.
500 Internal Server Error — the backend operation failed. Retry with exponential backoff; contact support if the error persists.

SDKs and OpenAPI spec

The API follows the OpenAPI 3.1 standard. You can download the full spec from the interactive docs and generate a client SDK in your preferred language using tools like:

OpenAPI Generator (openapi-generator-cli) — supports 50+ languages.
Swagger Codegen — the classic option, also multi-language.

Browse the full interactive documentation at alugha.com/api-docs – the Scalar-powered UI lets you inspect every endpoint, view schemas, and send test requests directly from the browser.

Good to know

The API is currently at version v2 (spec version 2.0.0-beta.0). Paths are prefixed with /v2.
File uploads are currently not supported through the API — use downloadFromUrl to pull files from a publicly reachable URL.
Every credit-consuming action in the API (transcription, translation, voiceover) costs the same credits as the equivalent action in the dubbr.
API access is included with Enterprise plans by default and available as an add-on on paid plans. See Understand alugha plans and credits.
Token scopes are granular — create a separate token for each integration and give it only the scopes it needs. Rotate tokens regularly.
Webhooks support any publicly reachable https:// URL — validate the payload on your end before acting on it.

Troubleshooting

401 Unauthorized:

Confirm the Authorization: Bearer header is set and the token is correct.
Tokens can be revoked from the API settings page — a revoked token keeps returning 401. Generate a fresh one.

403 Forbidden:

The token is valid but lacks the scope for this operation. Regenerate with the required scope selected.
Some endpoints require account-level permissions (for example, Enterprise-only add-ons). Check your plan.

downloadFromUrl fails or times out:

The URL must be publicly reachable without authentication. Presigned URLs with short expiries are recommended.
Very large files may hit timeouts — keep files under a few GB or split into multiple videos.

Webhook never fires:

Your webhook URL must return 2xx quickly — long-running handlers may retry. Acknowledge the payload first, then queue any heavy work.
Check that the URL is reachable from the public internet — internal/VPN-only endpoints will not work.

Was this article helpful?