Developers · early access

build with faluda

Put a live, lip-synced avatar in your app or stream with one REST API. Five Indian languages, WebRTC or RTMP output, and an AI label built in.

Get a sandbox key Read the quickstart

Preview mode. The API is in private early access. Endpoints, limits and names may change before launch. This frontend does not issue real API keys.

Overview

The faluda API gives you avatars that talk. Create a session, send it text or stream audio, and the avatar speaks with lip-sync and expressions. Output goes to WebRTC in your app or to an RTMP ingest such as YouTube Live.

Live sessionsReal-time avatars over WebRTC or RTMP.

5 languagesEnglish, Hindi, Tamil, Kannada, Malayalam.

11 ready avatarsOr create a consented digital twin from a photo.

Offline rendersScripts to 9:16 or 16:9 clips for reels and VOD.

WebhooksSession and render events pushed to your server.

AI label built inOn by default, so your viewers know.

Base URL https://api.faluda.ai/v1 · JSON over HTTPS · times in UTC ISO 8601

Quickstart

Get a key. Sandbox key issuance will be connected to your dashboard later.
Create a session with an avatar and output.
Make it speak by sending text in a supported language.
End the session when you are done.

# 1. create a live session
curl -X POST https://api.faluda.ai/v1/sessions \
  -H 'Authorization: Bearer $FALUDA_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"avatar_id":"aanya","language":"hi","output":{"type":"webrtc"},"ai_label":true}'

# 2. make the avatar speak
curl -X POST https://api.faluda.ai/v1/sessions/ses_8fK2x9/speak \
  -H 'Authorization: Bearer $FALUDA_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"text":"नमस्ते!","language":"hi"}'

# 3. end it
curl -X DELETE https://api.faluda.ai/v1/sessions/ses_8fK2x9 \
  -H 'Authorization: Bearer $FALUDA_API_KEY'

For RTMP, use output.type = rtmp with your ingest URL and stream key. The examples are illustrative, not connected to an active API.

Authentication

Send the API key as a Bearer token. Keep keys on your server, never in public client code. For browser clients, create a session server-side and deliver only a short-lived token.

Authorization: Bearer fal_test_xxxxxxxxxxxxxxxx

fal_test_ is the proposed sandbox key prefix; fal_live_ will require approval. Add an Idempotency-Key to POST requests to avoid duplicate requests when retrying.

API reference

GET`/avatars`

List avatars

Returns the ready-made avatars you can stream with, including languages and style.

Parameter	Type	Required	Description
`language`	string	no	Filter by language: en, hi, ta, kn, ml
`style`	string	no	Filter by style, e.g. desi-glam, streetwear

Response

{
  "data": [
    {
      "id": "aanya",
      "name": "Aanya",
      "style": "Desi Glam",
      "languages": [
        "en",
        "hi",
        "ta",
        "kn",
        "ml"
      ],
      "preview_url": "https://cdn.faluda.ai/avatars/aanya.webp"
    }
  ],
  "has_more": false
}

GET`/avatars/{id}`

Get an avatar

Fetch one avatar by id.

Parameter	Type	Required	Description
`id`	string	yes	Avatar id, e.g. aanya

Response

{
  "id": "aanya",
  "name": "Aanya",
  "style": "Desi Glam",
  "languages": [
    "en",
    "hi",
    "ta",
    "kn",
    "ml"
  ],
  "official": false
}

POST`/sessions`

Create a live session

Starts a real-time avatar session. Connect to the returned WebRTC URL, or push to your own RTMP endpoint. The avatar lip-syncs to text you send or audio you stream.

Parameter	Type	Required	Description
`avatar_id`	string	yes	Avatar to use
`language`	string	no	en, hi, ta, kn or ml. Default en
`voice`	string	no	warm, spark, calm, whisper, chill, deep or hype
`output.type`	string	yes	webrtc or rtmp
`output.rtmp_url`	string	rtmp only	Your ingest URL, e.g. YouTube or Twitch
`output.stream_key`	string	rtmp only	Stream key. Stored encrypted, never returned
`ai_label`	boolean	no	Show the AI avatar label. Default true. Required for photoreal avatars on most platforms
`metadata`	object	no	Your own key-value data, returned in webhooks

Request

{
  "avatar_id": "aanya",
  "language": "hi",
  "voice": "warm",
  "output": {
    "type": "webrtc"
  },
  "ai_label": true
}

Response

{
  "id": "ses_8fK2x9",
  "status": "ready",
  "avatar_id": "aanya",
  "language": "hi",
  "output": {
    "type": "webrtc",
    "url": "wss://rtc.faluda.ai/ses_8fK2x9",
    "token": "eyJhbGciOi..."
  },
  "ai_label": true,
  "expires_at": "2026-10-27T10:30:00Z"
}

GET`/sessions/{id}`

Get a session

Returns session state and usage so far.

Parameter	Type	Required	Description
`id`	string	yes	Session id

Response

{
  "id": "ses_8fK2x9",
  "status": "live",
  "started_at": "2026-10-27T09:58:12Z",
  "duration_seconds": 412
}

POST`/sessions/{id}/speak`

Make the avatar speak

Queues text for the avatar to say. Lip-sync and expression are generated automatically. Send interrupt: true to cut off current speech.

Parameter	Type	Required	Description
`text`	string	yes	Up to 1,000 characters
`language`	string	no	Overrides the session language
`voice`	string	no	Overrides the session voice
`interrupt`	boolean	no	Stop current speech first. Default false

Request

{
  "text": "Welcome to the stream, everyone!",
  "interrupt": false
}

Response

{
  "utterance_id": "utt_31aQ",
  "status": "queued"
}

DELETE`/sessions/{id}`

End a session

Ends the session and stops billing for it.

Parameter	Type	Required	Description
`id`	string	yes	Session id

Response

{
  "id": "ses_8fK2x9",
  "status": "ended",
  "duration_seconds": 1260
}

POST`/renders`

Render a clip

Creates an offline video of an avatar saying a script. Good for reels, intros and VOD. Poll the render, or use the render.completed webhook.

Parameter	Type	Required	Description
`avatar_id`	string	yes	Avatar to use
`script`	string	yes	Text to speak, up to 5,000 characters
`language`	string	no	Default en
`aspect`	string	no	9:16 or 16:9. Default 9:16
`resolution`	string	no	720p or 1080p. Default 720p

Request

{
  "avatar_id": "kabir",
  "script": "Aaj ka stream shuru hone wala hai!",
  "language": "hi",
  "aspect": "9:16"
}

Response

{
  "id": "rnd_77Hd",
  "status": "processing"
}

GET`/renders/{id}`

Get a render

Returns the render status and, when done, a download URL valid for 24 hours.

Parameter	Type	Required	Description
`id`	string	yes	Render id

Response

{
  "id": "rnd_77Hd",
  "status": "completed",
  "video_url": "https://cdn.faluda.ai/renders/rnd_77Hd.mp4",
  "duration_seconds": 6.4
}

POST`/twins`

Create a digital twin

Creates a custom avatar from a photo of a person who has given consent. Twins are reviewed before they go live. Official creator twins need a signed agreement.

Parameter	Type	Required	Description
`name`	string	yes	Display name
`photo_url`	string	yes	Front-facing photo, eyes open, mouth closed
`consent`	object	yes	consent.given (true) and consent.contact_email of the person pictured

Request

{
  "name": "My twin",
  "photo_url": "https://example.com/me.jpg",
  "consent": {
    "given": true,
    "contact_email": "me@example.com"
  }
}

Response

{
  "id": "twn_5Pq1",
  "status": "in_review"
}

GET`/usage`

Get usage

Returns minutes used in the current billing period.

Parameter	Type	Required	Description
`period`	string	no	Month, e.g. 2026-10. Default current month

Response

{
  "period": "2026-10",
  "live_minutes": 182.5,
  "render_minutes": 14.2,
  "concurrent_peak": 3
}

Webhooks

Register an HTTPS endpoint for JSON events. The intended contract responds within 10 seconds; retries would use exponential backoff. This is a preview specification.

Event	When
`session.started`	The avatar is live.
`session.ended`	The session ended, with its duration.
`render.completed`	A clip is ready to download.
`render.failed`	A render could not finish.
`twin.ready`	A digital twin passed review.
`twin.rejected`	A twin was not approved, with a reason.

Example event

{
  "type": "session.ended",
  "data": { "session_id": "ses_8fK2x9", "duration_seconds": 1260 }
}

Errors and limits

The proposed API returns JSON errors with an HTTP status and error.code.

Status	Code	Meaning
`400`	invalid_request	A parameter is missing or malformed.
`401`	unauthorized	Missing or invalid API key.
`403`	forbidden	Your key cannot use this resource, or consent is missing for a twin.
`404`	not_found	No such avatar, session or render.
`409`	session_limit	Too many concurrent sessions for your plan.
`422`	unsupported	Language, voice or output type is not supported for this avatar.
`429`	rate_limited	Too many requests. Retry after the Retry-After header.
`5xx`	server_error	A server error. Retry with the same Idempotency-Key.

Preview defaults

Limit	Sandbox	Approved (live) keys
`Requests per minute`	60	600
`Concurrent sessions`	2	Set per plan
`Session length`	10 minutes	Set per plan
`Watermark`	Yes	No

These limits are illustrative preview values and may change before backend launch.

SDKs and tools

Plain REST is the proposed first integration; native SDKs and no-code tools are on the roadmap.

REST APIPreview

Works from any language.

Web SDK (JavaScript)Private preview

Connect a session and render the avatar in a page.

Python and Node SDKsPlanned

Typed clients for the REST API.

iOS and Android SDKsPlanned

Embed live avatars in native apps.

faluda CameraComing soon

A virtual camera for OBS, Instagram and YouTube.

OBS pluginPlanned

Add a faluda source straight inside OBS.

Responsible use

AI label. ai_label defaults to true. Keep it on for photoreal avatars.
Consent for twins. Only create a digital twin of someone who has agreed; human review is planned.
Official avatars. Official creator twins require the creator's signed approval.
No impersonation. Do not represent an avatar as an unconsenting real person.
Your data. Photo/script handling and deletion require a production backend and policy review.

Request API access

Sandbox key creation will be enabled from the dashboard when the backend is connected. No active keys are issued from this preview.

Need live keys or higher limits?

Tell us what you're building. This frontend form validates locally until the access API is connected.

← Back to home

Overview

Quickstart

Authentication

API reference

GET/avatars

Response

GET/avatars/{id}

Response

POST/sessions

Request

Response

GET/sessions/{id}

Response

POST/sessions/{id}/speak

Request

Response

DELETE/sessions/{id}

Response

POST/renders

Request

Response

GET/renders/{id}

Response

POST/twins

Request

Response

GET/usage

Response

Webhooks

Example event

Errors and limits

Preview defaults

SDKs and tools

Responsible use

Request API access

Need live keys or higher limits?

GET`/avatars`

GET`/avatars/{id}`

POST`/sessions`

GET`/sessions/{id}`

POST`/sessions/{id}/speak`

DELETE`/sessions/{id}`

POST`/renders`

GET`/renders/{id}`

POST`/twins`

GET`/usage`