Atmee.aiDocs
APIAPI referenceGeneration

Design a voice from a description

POST
/v1/generation/voices

Designs voice previews from a description of how the voice should sound. Every preview runs 10 to 60 seconds, the length a v2 avatar's voice sample needs: a preview under 10 seconds is made once more with a longer read and dropped if it is still short, and one over 60 seconds is dropped. A preview whose length the provider did not report has durationSeconds: null.

sampleText, when given, is what every preview says, in language: 220-600 characters for Latin and Cyrillic scripts, 120-300 for Chinese, Japanese and Korean, 180-450 for Hindi. Without it, Atmee writes a greeting from the description, long enough for 10 seconds. Each preview reports the text it actually speaks (spokenText).

Each preview is returned as upload:<uploadId>, which POST /v1/avatars (assets.voice) and the JSON form of PUT /v1/avatars/{avatarId}/voice take as they are, plus a short-lived url to play it. The price, charging and Idempotency-Key work as for POST /v1/generation/portraits. Requires generation:write and avatars:write.

Authorization

headerX-Api-Key<token>

Secret embed API key (sk_atmee_...; keys minted before 2026-09 carry sk_live_...), held by the customer's own backend and never sent to a browser. Format: X-Api-Key: sk_atmee_....

Header Parameters

Idempotency-Key*string

A new UUID minted for this request. Reuse it only to retry the same request: a retry never charges twice and returns the first result. A malformed key, or a key already used with different inputs, gets 400 invalid_input.

Lengthlength <= 255

Request Body

application/json
  1. body
voiceDescription*string

How the voice should sound: age, tone, pace, accent, character.

Length20 <= length <= 1000
avatarName?string

The avatar's name; the written sample says it.

Lengthlength <= 100
language?string

The language the voice speaks. Default en.

Value in"en""zh-TW""zh-CN""ja""ko""fr""vi""es""de""hi""ru"
sampleText?string

What every preview says, in language (per-script lengths in the operation's description). Absent, Atmee writes it.

Lengthlength <= 600

Response Body

The voice previews (or the replayed first result).

application/json
  1. response
voices*array<>
Items1 <= items
language*string
Value in"en""zh-TW""zh-CN""ja""ko""fr""vi""es""de""hi""ru"
microcreditsCharged*integer

What this call charged (100 microcredits = 1 credit); 0 on a replay.

replayed*boolean

True when an earlier call with the same Idempotency-Key was replayed.

failedProviders*array<string>

The providers that returned nothing usable.

Example Request
curl -X POST 'https://api.atmanity.us/v1/generation/voices' \  -H 'Idempotency-Key: string' \  -H 'Content-Type: application/json' \  -d '{  "voiceDescription": "stringstringstringst"}'
Example Response
{  "voices": [    {      "upload": "upload:3f1c2a9e-8d4b-4f6a-9c2e-1b7d5a0e4c11",      "url": "http://example.com",      "expiresAt": "2019-08-24T14:15:22Z",      "provider": "string",      "spokenText": "string",      "durationSeconds": 0,      "unavailable": true    }  ],  "language": "en",  "microcreditsCharged": 0,  "replayed": true,  "failedProviders": [    "string"  ]}

Enhance or restyle a portrait photo POST

Crops the caller's own photo to a square and returns up to four square portraits, one per image provider.

Render a video clip from an image and a prompt POST

Renders a short mp4 (1 to 15 seconds, 25 fps) of the person or character in image, moving as prompt describes, optionally speaking audio.

Design a voice from a description — Atmee Docs