Neurall

Avatar Video

videovideo/avatar

Make any face talk: a person, a character, an animal, even a painted portrait.

A faceA faceSaying whatever you send

One image and one voice. Either send text plus a voice id and we synthesize the speech, or send your own audio file and we lipsync to it. The face can be anything with a mouth facing the camera: a person, a character, an animal, even a painted portrait.

Billed per started 15 seconds of audio. $0.75 per started block at 720p, $1.13 at 1080p. Live rate from GET /v3/pricing.

A complete call

Make one photograph say a line, in a catalog voice.

1Upload the face

POST /v3/files/upload returns a file id. Send the audio in the same request if you are bringing your own instead of a voiceId.

curl -X POST "https://api.neurall.io/v3/files/upload" \
  -H "Authorization: nl-YOUR_API_KEY" \
  -F "files=@face.jpg"

It answers with the file ids

{
  "files": [
    {
      "id": "f_9c21e0b4",
      "originalName": "face.jpg",
      "size": 655380
    }
  ]
}

2Submit the render

POST /v3/generations with the id from step 1 in args.image, and either voiceId plus text, or audio.

curl -X POST "https://api.neurall.io/v3/generations" \
  -H "Authorization: nl-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "feature": "video/avatar",
    "args": {
      "image": "f_9c21e0b4",
      "voiceId": "aria",
      "text": "Whatever you have a picture of, I can make it talk.",
      "resolution": "720p"
    },
    "variants": {
      "resolution": "720p"
    }
  }'

It answers immediately

{
  "generation": {
    "id": "2c4a…",
    "feature": "video/avatar",
    "kind": "video",
    "status": "pending"
  }
}

3Poll until it lands

Poll GET /v3/generations/{id}, or pass webhookUrl and skip polling.

# repeat every 5s or so until status is done, error or timeout
curl "https://api.neurall.io/v3/generations/9f2c1d84-6a3b-4f21-9c77-2f0a1b8e5d43" \
  -H "Authorization: nl-YOUR_API_KEY"

Once status is done

{
  "generation": {
    "status": "done",
    "output": {
      "video": "https://cdn.neurall.io/…/video.mp4",
      "mime": "video/mp4"
    }
  }
}

output holds the finished asset on a signed CDN URL. Download it rather than hotlinking: API-created outputs expire 24 hours after the request.

Arguments

imagestringrequired
Exactly one entry: the face that speaks. A file id from POST /v3/files/upload.
  • PNG, JPEG, WebP, GIF, HEIC or AVIF, up to 30 MB and 30 megapixels per file, 10 files per upload request.
  • An uploaded file is deleted 24 hours after it lands, so upload again for a later render rather than caching an id.
  • Exactly one image. Front-facing with a visible mouth: a profile or a covered mouth has nothing to animate.

How the prompt refers to this

args.imageThe face
Nothing to write. It is animated as photographed.
voiceIdstring
A catalog voice (GET /v3/voices) or one of your cloned voices. Pair it with text. The alternative to audio.
textstring
What it says. [pause=1.5] inserts an exact 1.5 second pause. Required when voiceId is set.
  • The spoken audio may not exceed 90 seconds; longer text is rejected rather than truncated.
audiostring
Your own recording instead of synthesis: a file id from POST /v3/files/upload. The alternative to voiceId plus text.
  • MP3, WAV, M4A, OGG, FLAC or WebM, up to 30 MB.
  • At most 90 seconds of audio.

How the prompt refers to this

args.audioYour recording
When present it replaces synthesis entirely; voiceId and text are ignored.
speednumberdefaults to 1
Relative pace against the voice's natural, already normalised speed.
  • Between 0.5 and 2.
resolution'720p' | '1080p'defaults to '720p'
Render resolution. It sets the billing rate too, so it rides in variants as well.

Send either voiceId plus text, or audio. Sending neither is a 400.

Output

Once status is done, the generation carries an output object with these fields. On any other status, output is absent.

videostring
The finished clip of the avatar delivering the script, as a URL. An MP4 with the voice track baked in.
  • A signed URL that expires 24 hours after the request (expiresAt on the generation). Download the file rather than hotlinking it.
mimestring
The clip's MIME type, e.g. video/mp4.

Limits and failure

Audio
At most 90 seconds, whether synthesized or uploaded.
Billing
Per started 15 second block, multiplied by the resolution.
Likeness
A real person as the face requires their permission; the Terms of Use cover it, there is nothing to send.
Render time
Short clips land in minutes, but a long script can take up to 90 minutes. A generation that has not finished in 2 hours is marked timeout and refunded.
Concurrency
Your plan caps how many generations run at once. Over it the API answers 429 with a Retry-After header.
Output lifetime
API-created outputs expire 24 hours after the request. Download the file rather than hotlinking it.
Deletion
DELETE /v3/generations/{id} removes the generation and its rendered assets immediately, rather than waiting for the 24 hour expiry. It does not refund anything and cannot cancel a render already in flight.
Failure
A failed or timed-out generation is refunded automatically.

Worth knowing

  • Animals and paintings work: the face does not have to be a real person.
  • Lipsync follows the audio, so a long pause in the text is a long pause on screen.