Fluen Studio API Reference

The API uses API key authentication. To obtain an API key:

1. Log in to your Fluen Studio account
2. Navigate to 'My Account' > 'API & Webhooks'
3. Click on 'Generate Secret Key'
4. Copy and store the secret key securely - it will only be shown once

Include your API key in all requests using the X-API-Key header. The API key gives you access to operate on all your workspaces and their associated assets.

Important: Keep your API key secure and never share it publicly. If you suspect your API key has been compromised, you can revoke it and generate a new one from the same page.

By default, captions created through the API complete on their own and any translations requested with them (or added later) start immediately: expect caption.completed followed by translation.completed with no action needed in between.

Teams that want captions reviewed by an editor before translation can pass captionPostEdit: true when creating the media. The caption track then waits in POST_EDIT status after transcription, and translations stay SCHEDULED until the captions are approved in the web editor. Approval is a web action; plan for it in your workflow before enabling the flag.

Already have subtitles? The "Create Media from captions" operation builds a captions-only media from an inline SRT: no upload and no transcription runs, and the caption track is ready immediately. Add translation languages to it and export the results. Translations are billed on the SRT's duration; the imported captions are free.

Every Fluen job (encode, transcription, translation, burn-in) runs asynchronously and takes anywhere from a few seconds to a few minutes to finish. Instead of polling GET /api/media/{mediaId}, register a webhook endpoint and Fluen will POST a signed JSON event to your URL the moment a job reaches a terminal state.

Manage endpoints with the /api/webhook-endpoints operations: register a URL plus an event-type filter, list, update, delete, rotate the signing secret, send a test ping, and inspect recent deliveries. The signing secret is shown only once, at creation and on rotate-secret. Each user can have at most 50 active endpoints.

Payloads are outbound and so do not appear as operations in this reference. The event catalog, payload shape, and signature scheme below are the stable contract: field names are additive and are never renamed once shipped.

Event catalog

A synthetic ping event is sent only by the test-endpoint operation and is never matched by a subscription.

Payload

Every delivery is an HTTP POST with Content-Type: application/json and this envelope:

{
  "id": "evt_9f2c4e1abd7e4f0e8a1c6b5d4e3f2a10",
  "type": "translation.completed",
  "apiVersion": "2026-07-01",
  "createdAt": "2026-07-10T14:12:09.482913Z",
  "data": {
    "mediaId": "aB3xK9",
    "mediaTitle": "Q3 townhall.mp4",
    "workspaceId": "ws_7Yn2",
    "trackId": "trk_Fr8",
    "languageId": "fr",
    "jobType": "TRANSLATION",
    "status": "COMPLETE"
  },
  "links": {
    "media": "https://api.fluen.ai/api/media/aB3xK9",
    "track": "https://api.fluen.ai/api/tracks/trk_Fr8"
  }
}

id is stable across retries of the same event: use it to deduplicate. links are absolute URLs to the canonical resources (GET), present when the event has a media/track. What you do with a track (export it or burn it in) is a separate call (see below), not a link. Each delivery also carries these headers:

Acting on an event

The mediaId / trackId in data are the durable handles. Common follow-ups:

• Export a track in any supported format: GET /api/tracks/{trackId}/export/{format}, where {format} is one of SRT, VTT, TXT, DOCX, PDF, SSA, TTML, ITT, SBV, STL (uppercase: the value binds case-sensitively).
• Burn subtitles into the video, producing an MP4 with hardcoded subtitles (what the web app calls an MP4 export; the API calls it a burn-in). This is a job, not a plain download: POST /api/tracks/{trackId}/burnin/{videoFormat} with no body (or {}) to render the track's saved style, {videoFormat} one of ORIGINAL, HIGHEST, HIGH, STANDARD (see the operation for what each resolution means). Wait for the burnin.completed event (or poll GET /api/tracks/{trackId}/burnin), then fetch a time-limited download URL from GET /api/tracks/{trackId}/burnin/{burnInId}/download.

Verifying signatures

Each delivery is signed with your endpoint's secret so you can confirm it came from Fluen and was not altered in transit. The X-Fluen-Signature header is t=<timestamp>,v1=<signature>, where the signature is HMAC-SHA256(secret, "<timestamp>.<raw-body>") rendered as lowercase hex.

To verify: recompute the HMAC over timestamp + "." + rawBody with your secret and compare it to v1 in constant time. Also reject deliveries whose timestamp is far from your clock: the timestamp is bound into the signature to prevent replay.

const crypto = require('crypto');

function verifyFluenWebhook(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(signatureHeader.split(',').map(kv => kv.split('=')));
  const expected = crypto.createHmac('sha256', secret)
    .update(parts.t + '.' + rawBody)
    .digest('hex');
  const signatureOk = parts.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300; // 5-minute tolerance
  return signatureOk && fresh;
}

Verify against the exact raw request body, before any JSON parsing or re-serialization.

Delivery, retries, and hygiene

• At-least-once. A retry can re-deliver an event you already received; deduplicate on the envelope id.
• Success is any 2xx within a 10-second timeout. Anything else, including timeouts and connection errors, is a failed attempt.
• Retries back off over roughly five hours: 30s, 2m, 10m, 1h, 4h (five retries after the first attempt), after which the delivery is abandoned.
• 410 Gone. If your endpoint responds 410, the subscription is deactivated immediately with no retries (REST Hooks convention). Return 410 when the receiving hook no longer exists.
• Auto-disable. After 15 consecutive abandoned deliveries an endpoint is disabled and its owner emailed; re-enable it with the update operation. This stops dead URLs from being retried forever.
• Retention. Delivery records stay queryable via the deliveries operation for 30 days.
• Only https URLs are accepted, and any URL resolving to a private or reserved IP range is rejected at registration and again at delivery time.

Zapier and Make

Endpoints follow the REST Hooks pattern, so Zapier instant triggers work directly (Zapier subscribes by creating an endpoint and unsubscribes by deleting it). The GET /api/webhook-endpoints/sample-events?type=<event-type> operation returns recent real events, or a representative example, so Zap builders can map fields before a live event fires. Make.com "custom webhook" triggers consume the same payloads.

Every plan, including the free one, can create API keys and use the full API surface and webhooks. Free accounts are limited in the number of successful jobs they can run, and their translations may be only partial. When a plan limit is reached, the API responds 402 (or 403 for unavailable features) with code FREE_TIER_LIMIT and a message that states the exact limit and carries an upgrade link; asynchronous jobs report plan-limit failures through the failure webhooks' reason field (e.g. FREE_DURATION_LIMIT). A partial translation carries isPartial: true and can be completed after upgrading. Building or testing an integration and need more room than the free plan allows? Email support@fluen.ai and tell us what you are working on.

Error responses carry a JSON body with a machine-readable code, a human-readable message, and, where useful, structured details:

{
  "code": "FREE_TIER_LIMIT",
  "message": "Upgrade to translate into more languages.",
  "details": { }
}

Codes in use: VALIDATION_ERROR (400), UNAUTHORIZED (401, missing or invalid credentials), FREE_TIER_LIMIT / INSUFFICIENT_CREDITS (402, upgrade or top up to proceed), NOT_FOUND (404), RATE_LIMITED (429), INTERNAL_ERROR (500). Asynchronous job failures surface as webhook reason values instead: INSUFFICIENT_CREDITS, FREE_DURATION_LIMIT. New codes may be added over time; existing ones are never renamed. A few legacy operations still return a bare message string; switch on the HTTP status first and treat code as a refinement.

API-key requests are rate limited per account: 120 requests/minute overall, and 10 requests/minute for Create Media. Past the limit, requests get 429 with a Retry-After header (seconds), X-RateLimit-Limit, and X-RateLimit-Remaining. Space out polling loops (webhooks avoid most polling) and retry after the indicated delay.

This namespace contains endpoints for retrieving the supported system languages.

This namespace contains endpoints to read, create, and update media objects.

This namespace contains endpoints to manage term bases and glossary terms for workspaces.

This namespace contains endpoints to export subtitle tracks and to import corrected subtitles into an existing caption track.

This namespace contains endpoints to read the current user details.

Webhook Endpoint Controller

Workspace management endpoints