NueForm

API vocale

Générez de la parole depuis votre propre code avec les voix de Voice Studio : une voix ou un script entier, 0,4 crédit par caractère prononcé dans toutes les langues, avec une estimation gratuite au préalable.

Générez de la parole depuis votre propre code avec NueSpeak Apex, les mêmes voix que dans Voice Studio. Les requêtes dépensent des crédits de votre solde NueForm : 0,4 crédit par caractère prononcé (environ 0,04 $ pour 1 000 caractères) dans toutes les langues, arrondi au crédit supérieur une fois par requête. Les estimations sont gratuites.

Tous les corps de requête et de réponse utilisent des noms de champs en snake_case. Les voix sont désignées par des identifiants nv_… et les générations par des identifiants gen_….

Les clés Voice fonctionnent avec tous les abonnements dès que votre compte a effectué un premier achat de crédits (ou dispose d'un abonnement payant) et a vérifié son adresse e-mail. Voir Clés de l'API vocale.

Endpoints
POST/api/v1/voicePOST/api/v1/voicePOST/api/v1/voice/streamGET/api/v1/voice/voicesDELETE/api/v1/voice/voices/:idGET/api/v1/voice/generationsGET/api/v1/voice/generations/:idGET/api/v1/voice/generations/:id/audioDELETE/api/v1/voice/generations/:idGET/api/v1/credits

Générer de la parole

POST/api/v1/voice

Génère l'audio et répond quand il est prêt (de façon synchrone, 5 000 caractères prononcés au maximum par requête). Envoyez Accept: audio/mpeg (ou audio/wav, audio/ogg, audio/basic, audio/*) pour recevoir l'audio lui-même ; sinon, la réponse est du JSON avec une audio.url authentifiée.

Les crédits sont prélevés au début de la requête. Les lignes qui échouent sont recréditées automatiquement, et rien de ce qui se termine par une erreur n'est facturé. Une requête facturée ne se termine jamais par une erreur : si son audio n'est pas prêt à temps, elle répond 202 avec un en-tête Location. Récupérez l'audio à cette adresse au lieu de renvoyer la requête.

Corps de la requête

modestring

"speak" (une voix lit text), "script" (plusieurs voix) ou "estimate" (voir Estimer le coût)

textstring

speak : les mots à lire

voicestring

Une voix nv_… de Lister les voix. Obligatoire pour speak ; dans un script, la voix des lignes sans balise de personnage

linesarray

script : des lignes structurées, chacune {"speaker", "voice", "text"} ou une pause {"pause_ms": 800} (jusqu'à 10 000)

scriptstring

script : le format multivoix, une ligne par personnage : [Maya] Did you hear that?

castarray

script : une voix pour chaque personnage balisé, [{"speaker": "Maya", "voice": "nv_…"}]

auto_convertboolean

Convertir d'abord un scénario ou une conversation collés (MAYA: Hi) au format multivoix. Gratuit, dans une limite quotidienne

auto_castboolean

Choisir une voix pour chaque personnage qui n'en a pas. Gratuit, dans une limite quotidienne. Envoyez language pour un script qui n'est pas en anglais

languagestring

Un nom ou un code de langue ("es", "Spanish"). Par défaut : la langue de la voix

qualitystring

"standard" (par défaut), "studio" ou "phone". Même prix

speednumber

De 0,85 à 1,15 (1 par défaut)

formatstring

"mp3" (par défaut), "wav", "ogg_opus" ou "mulaw_8k"

max_creditsinteger

Refuser la requête (409, rien n'est facturé) si elle devait coûter plus

reuseboolean

true par défaut : une requête identique faite au cours des 30 derniers jours reçoit cet audio pour 0 crédit

saveboolean

true conserve l'audio jusqu'à ce que vous le supprimiez. Par défaut : supprimé après 30 jours

retake_ofstring

Refaire une génération (voir Reprises)

titlestring

Son titre dans votre Library

Champs de la réponse

idstring

La génération (gen_…)

statusstring

"ready", "rendering" (202 : encore en cours de génération), "partial" (certaines lignes ont échoué et ne coûtent rien) ou "failed"

audioobject or null

url (envoyez votre clé API), format, sample_rate, duration_seconds, retained_until

creditsobject

estimated, charged (ce que cette requête a facturé) et remaining

linesarray

script uniquement : speaker, voice, text, status, start_ms, end_ms et credits de chaque ligne

retakes_remaininginteger

Reprises gratuites restantes pour ce clip

reusedboolean

L'audio d'une requête identique antérieure, pour 0 crédit

Exemples de code

bash
curl -X POST https://nueform.io/api/v1/voice \
  -H "Authorization: Bearer $NUEFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: audio/mpeg" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "mode": "speak",
    "voice": "nv_7QmS2xK9aLpe3vT8a",
    "text": "Fresh bread every morning at seven. Croissants too. See you on Main Street."
  }' \
  --output speech.mp3 --dump-header -

Ce texte compte 75 caractères prononcés : il coûte donc 30 crédits (75 × 0,4).

En-têtes de réponse

text
HTTP/1.1 200 OK
Content-Type: audio/mpeg
NueForm-Generation-Id: gen_2cH4kXyQ9vLmNp3Rs
NueForm-Credits-Estimated: 30
NueForm-Credits-Charged: 30
NueForm-Credits-Remaining: 48730
NueForm-Rate-Card: 1
NueForm-Retakes-Remaining: 2
NueForm-Audio-Duration: 4.8
Idempotent-Replayed: false
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 2026-11-04T18:13:00.000Z

Réponse JSON

json
{
  "data": {
    "id": "gen_2cH4kXyQ9vLmNp3Rs",
    "object": "voice.generation",
    "status": "ready",
    "mode": "speak",
    "source": "api",
    "voice": { "id": "nv_7QmS2xK9aLpe3vT8a", "name": "Amara" },
    "language": "English",
    "characters": 75,
    "audio": {
      "url": "https://nueform.io/api/v1/voice/generations/gen_2cH4kXyQ9vLmNp3Rs/audio?format=mp3",
      "format": "mp3",
      "sample_rate": 24000,
      "duration_seconds": 4.8,
      "retained_until": "2026-12-04T18:12:00.000Z"
    },
    "credits": { "estimated": 30, "charged": 30, "remaining": 48730 },
    "retakes_remaining": 2,
    "reused": false,
    "created_at": "2026-11-04T18:12:00.000Z"
  },
  "meta": { "rate_card": "1" }
}

Scripts

Un script fait parler plusieurs voix dans un seul fichier audio. Envoyez des lines structurées (sans aucune analyse) ou un script au format multivoix avec son cast. Les pauses ({"pause_ms": 800}, ou (pause 2s) dans un script) ne coûtent rien ; seuls les caractères prononcés sont facturés.

La réponse ajoute lines : où chaque ligne commence et finit dans l'audio, son statut et ce que représentent ses caractères (credits, en décimal). La requête est facturée une seule fois, arrondie au crédit supérieur. Une ligne qui échoue affiche "credits": 0 et ne coûte rien.

Avec auto_convert, un scénario ou une conversation collés sont d'abord convertis ; avec auto_cast, chaque personnage sans voix en reçoit une.

Exemple de requête

json
{
  "mode": "script",
  "lines": [
    { "speaker": "Maya", "voice": "nv_7QmS2xK9aLpe3vT8a", "text": "Did you hear that?" },
    { "speaker": "Leo", "voice": "nv_P3vT8aLeQ2mwX4kZ9", "text": "Hear what?" },
    { "pause_ms": 800 },
    { "speaker": "Maya", "voice": "nv_7QmS2xK9aLpe3vT8a", "text": "Exactly. Nothing." }
  ],
  "format": "wav"
}

Ou le format multivoix

json
{
  "mode": "script",
  "script": "[Maya] Did you hear that?\n[Leo] Hear what?\n(pause 1s)\n[Maya] Exactly. Nothing.",
  "auto_cast": true
}

Estimer le coût

POST/api/v1/voice

"mode": "estimate" accepte le même corps que speak ou script et répond avec le coût exact, sans rien générer. C'est gratuit et cela ne compte pas dans vos limites de génération (jusqu'à 300 par minute et par clé).

Champs de la réponse

charactersinteger

Caractères prononcés : ce qui est facturé

creditsinteger

Exactement ce que la requête facturerait

seconds_estimatednumber

La durée approximative de l'audio

balanceinteger

Votre solde actuel

enoughboolean

Votre solde (et la limite mensuelle de la clé, s'il y en a une) le couvre

Exemple

bash
curl -X POST https://nueform.io/api/v1/voice \
  -H "Authorization: Bearer $NUEFORM_API_KEY" \
  -d '{"mode": "estimate", "voice": "nv_7QmS2xK9aLpe3vT8a", "text": "Fresh bread every morning at seven. Croissants too. See you on Main Street."}'
json
{
  "data": {
    "object": "voice.estimate",
    "characters": 75,
    "credits": 30,
    "seconds_estimated": 4.8,
    "balance": 48760,
    "enough": true
  },
  "meta": { "rate_card": "1" }
}

Diffuser la voix en continu

POST/api/v1/voice/stream

Envoie l'audio pendant qu'il est généré, pour que votre application commence à le lire en une seconde environ au lieu d'attendre le clip entier : un agent, un bot vocal, un lecteur. Une voix lit text. Avec un moteur vocal déjà prêt, le premier audio arrive généralement en 1 à 2 secondes, quelle que soit la longueur du texte.

Le prix est celui de Générer de la parole : 0,4 crédit par caractère prononcé, arrondi au crédit supérieur une fois par requête et débité au début du flux. Un flux accepte jusqu'à environ 200 secondes de parole : environ 3 100 caractères d'anglais, moins dans les langues parlées plus lentement (un texte plus long donne 413 TEXT_TOO_LONG avec max_characters). Pour un texte plus long, envoyez plusieurs flux ou utilisez POST /api/v1/voice.

Avant le premier octet, toute erreur est une erreur normale et ne coûte rien : si le moteur vocal échoue avant tout audio, le débit est recrédité (500, ou 503 WARMING_UP avec Retry-After pendant que le moteur démarre). Après le premier octet, le statut ne peut plus changer : un flux qui échoue en cours de route s'arrête avant sa fin, et votre client HTTP signale un corps incomplet. Utilisez NueForm-Generation-Id avec Obtenir une génération pour voir la copie enregistrée et ce qu'elle a coûté. Si vous raccrochez, le flux est quand même terminé et enregistré, et il n'est pas recrédité.

Chaque flux est aussi enregistré comme une génération : il apparaît dans votre Library et Télécharger l'audio le sert, normalisé comme chaque clip.

Flux ou /voice ? Utilisez le flux quand quelqu'un attend de l'entendre (agents, bots vocaux, lecture à voix haute). Utilisez POST /api/v1/voice pour les fichiers, les scripts à plusieurs voix, speed, les reprises et les estimations. Les outils MCP ne diffusent pas en continu : ils créent l'audio à la manière de /voice.

Corps de la requête

voicestring

Une voix nv_… de Lister les voix

textstring

Les mots à lire

formatstring

"mp3" (par défaut, pour les navigateurs), "pcm_24k" (PCM brut 16 bits little-endian mono à 24 000 Hz, pour les agents) ou "mulaw_8k" (G.711 μ-law à 8 kHz, pour la téléphonie ; "ulaw_8000" fonctionne aussi)

languagestring

Un nom ou un code de langue. Par défaut : la langue propre à la voix

qualitystring

"standard" (par défaut ; "phone" pour mulaw_8k), "studio" ou "phone". Même prix

max_creditsinteger

Refuser la requête (409, rien n'est facturé) si elle devait coûter plus

saveboolean

true conserve la copie enregistrée jusqu'à ce que vous la supprimiez. Par défaut : supprimée après 30 jours

titlestring

Son titre dans votre Library

speed, les scripts, retake_of et reuse ne sont pas disponibles sur un flux (400, reason: "not_on_stream").

Exemples de code

bash
curl -N -X POST https://nueform.io/api/v1/voice/stream \
  -H "Authorization: Bearer $NUEFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"voice": "nv_7QmS2xK9aLpe3vT8a", "text": "Fresh bread every morning at seven.", "format": "mp3"}' \
  --output stream.mp3

Ce texte compte 35 caractères prononcés : il coûte donc 14 crédits (35 × 0,4).

En-têtes de réponse

text
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Transfer-Encoding: chunked
NueForm-Generation-Id: gen_2cH4kXyQ9vLmNp3Rs
NueForm-Credits-Estimated: 14
NueForm-Credits-Charged: 14
NueForm-Credits-Remaining: 48716
NueForm-Rate-Card: 1
NueForm-Audio-Format: pcm_24k
NueForm-Audio-Encoding: pcm_s16le
NueForm-Audio-Sample-Rate: 24000
NueForm-Audio-Channels: 1
X-Accel-Buffering: no

Reprises

Envoyez {"mode": "speak", "retake_of": "gen_…"} pour refaire une génération avec les mêmes mots, voix, langue, qualité et vitesse. Avec retake_of, seuls mode, format, max_credits et save sont acceptés.

  • Gratuite deux fois dans les 24 heures suivant la génération, tant que les reprises gratuites de la clé ce mois-ci ne dépassent pas un quart des caractères qui lui ont été facturés ce mois-ci. Une reprise gratuite garde le même identifiant gen_….
  • Sinon, c'est une nouvelle génération, facturée comme toute requête (0,4 crédit par caractère), et retake_of indique la génération reprise.

Envoyez "mode": "estimate" avec retake_of pour le savoir à l'avance : la réponse indique "free": true ou ce que cela coûterait.

Idempotence

Envoyez un en-tête Idempotency-Key (1 à 255 caractères, par exemple un UUID) avec les requêtes speak et script, et une nouvelle tentative ne pourra jamais facturer deux fois :

  • la même clé avec le même corps renvoie ce que la première requête a généré, sans rien facturer (Idempotent-Replayed: true, NueForm-Credits-Charged: 0) ;
  • la même clé avec un autre corps donne 409 CONFLICT avec reason: "idempotency_conflict" ;
  • tant que la première requête est en cours, 409 CONFLICT avec reason: "request_in_progress" et Retry-After.

Les clés sont conservées 24 heures, par clé API.

Sur un flux, la même clé avec le même corps répond en JSON : la génération créée par la première requête (elle n'est pas diffusée à nouveau).

En-têtes de réponse

Chaque réponse indique ce qu'elle a coûté :

En-têteSignification
NueForm-Generation-IdLa génération (gen_…)
NueForm-Credits-EstimatedLe prix annoncé pour la requête
NueForm-Credits-ChargedCe que cette requête a facturé, après tout recrédit automatique (0 pour une estimation, un clip réutilisé, une reprise gratuite, une relecture et toute erreur)
NueForm-Credits-RemainingVotre solde ensuite
NueForm-Rate-CardLa version de la grille tarifaire appliquée
NueForm-Retakes-RemainingReprises gratuites restantes pour ce clip
NueForm-Audio-DurationLa durée de l'audio en secondes
Idempotent-ReplayedAvec une Idempotency-Key : si cette réponse correspond à une requête antérieure
NueForm-Audio-Format, NueForm-Audio-Encoding, NueForm-Audio-Sample-Rate, NueForm-Audio-ChannelsL'audio d'un flux : son format, son encodage, sa fréquence d'échantillonnage et ses canaux
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-ResetLes requêtes de cette clé dans la minute en cours (voir Limites de débit)

Lister les voix

GET/api/v1/voice/voices

Les voix prédéfinies de NueForm, puis vos propres voix et celles de vos équipes, chacune avec son identifiant nv_…, sa langue, un aperçu gratuit et son débit. Gratuit.

Paramètres de requête

sourcestring

"all" (par défaut), "stock" ou "mine"

languagestring

Un nom ou un code de langue

genderstring

Par exemple "female"

qstring

Rechercher dans les noms, les styles et les libellés

featuredboolean

true : uniquement les voix prédéfinies mises en avant

Réponse

json
{
  "data": [
    {
      "id": "nv_7QmS2xK9aLpe3vT8a",
      "object": "voice",
      "name": "Amara",
      "source": "stock",
      "type": "clone",
      "language": "English",
      "language_label": "English (US)",
      "gender": "female",
      "age": null,
      "style": "Warm",
      "featured": true,
      "preview_url": "https://nueform.io/voice-previews/amara.mp3",
      "team_id": null,
      "can_delete": false,
      "chars_per_second": 15.5,
      "created_at": null
    }
  ],
  "meta": { "count": 1 }
}

Supprimer une voix

DELETE/api/v1/voice/voices/:id

Supprime définitivement l'une de vos voix : son échantillon, ses prompts et son aperçu, puis la voix. Les crédits ne sont pas remboursés. Tant que des formulaires ou des numéros de téléphone utilisent encore la voix, la réponse est 409 CONFLICT avec reason: "voice_in_use" et leur nombre ; envoyez ?replacement=nv_… pour les faire d'abord passer à une autre voix.

Réponse

json
{
  "data": {
    "id": "nv_9LmQ2xT4aPe7vK3sW",
    "object": "voice",
    "deleted": true,
    "switched": { "forms": 2, "numbers": 1 },
    "forms_to_republish": 1
  }
}

Lister les générations

GET/api/v1/voice/generations

Vos générations, des plus récentes aux plus anciennes. Passez à la page suivante avec meta.next_cursor.

Paramètres de requête

limitinteger

De 1 à 100 (20 par défaut)

cursorstring

next_cursor de la page précédente

sourcestring

Uniquement celles créées via "api", "studio", "mcp" ou "app"

Réponse

json
{
  "data": [
    { "id": "gen_2cH4kXyQ9vLmNp3Rs", "object": "voice.generation", "status": "ready", "credits": { "charged": 30 } }
  ],
  "meta": { "next_cursor": null, "has_more": false }
}

Obtenir une génération

GET/api/v1/voice/generations/:id

Une génération, avec ses lines pour un script. Ici, credits.charged correspond à ce qu'elle a coûté au total, après tout recrédit automatique.

Télécharger l'audio

GET/api/v1/voice/generations/:id/audio

L'audio lui-même, diffusé avec votre clé API (plages d'octets prises en charge). ?format= vaut mp3 (par défaut), wav, ogg_opus ou mulaw_8k. L'Ogg/Opus et le μ-law 8 kHz sont créés à la première demande : un 202 signifie « redemandez après Retry-After secondes ». Gratuit.

Supprimer une génération

DELETE/api/v1/voice/generations/:id

Supprime définitivement la génération et son audio. Les crédits ne sont pas remboursés. Une génération encore en cours répond 409 CONFLICT avec reason: "still_rendering".

Consulter vos crédits

GET/api/v1/credits

Le solde sur lequel votre clé dépense, le mois de la clé et la grille tarifaire. En lecture seule, avec une clé Voice ou une clé à accès complet.

Champs de la réponse

balanceinteger

Les crédits que vous pouvez dépenser maintenant (10 000 crédits = 1 $)

approxstring

Le solde en dollars

keyobject

monthly_credit_limit de cette clé (null = aucune), spent_this_month, paused et resets_at (le 1er, UTC)

voice_apiobject

credits_per_character (0,4), le mode d'arrondi, et le fait que les estimations sont gratuites

rate_cardobject

Tous les prix, par action

Réponse

json
{
  "data": {
    "object": "credits",
    "balance": 48730,
    "approx": "≈ $4.87",
    "currency": "usd",
    "frozen": false,
    "key": {
      "id_prefix": "nf_a1b2c3d4",
      "monthly_credit_limit": 100000,
      "spent_this_month": 1240,
      "paused": false,
      "resets_at": "2026-12-01T00:00:00.000Z"
    },
    "voice_api": { "credits_per_character": 0.4, "rounding": "up_per_request", "estimate_free": true }
  },
  "meta": { "rate_card": "1" }
}

Tarifs

QuoiCréditsEn dollars
Parole via l'API vocale0,4 par caractère prononcé, dans toutes les languesenviron 0,04 $ pour 1 000 caractères
Une estimation0gratuit
Un clip réutilisé (reuse)0gratuit
Une reprise0 deux fois dans les 24 heures (usage raisonnable), puis 0,4 par caractère

Les crédits s'achètent par packs (à partir de 5 $ pour 50 000 crédits) et n'expirent jamais. Une clé peut avoir une limite mensuelle de crédits : une fois ce montant dépensé, ses requêtes de synthèse et de suppression reçoivent 403 FORBIDDEN avec reason: "key_limit_reached" jusqu'au 1er du mois (elle peut toujours lister et télécharger ce qu'elle a généré), et vos autres clés continuent de fonctionner. Les requêtes sont payées avec les crédits choisis par le propriétaire de la clé dans Payer Voice Studio avec, dans le Portefeuille : les siens, sauf s'il a choisi une équipe. Une équipe qui ne peut pas payer n'est jamais remplacée par ses propres crédits : la requête reçoit 403 FORBIDDEN avec reason: "team_payer_unavailable", ou reason: "member_cap_reached" une fois son plafond mensuel de membre atteint, et rien n'est facturé.

Erreurs

Toutes les erreurs utilisent le format d'erreur standard, et rien de ce qui se termine par une erreur n'est facturé. Les plus courantes :

StatutcodeQuand
402INSUFFICIENT_CREDITSVotre solde ne couvre pas la requête (credits_required, credits_available, top_up_url ; payer: "team" quand c'est l'équipe avec laquelle paie le propriétaire de la clé qui manque de crédits : top_up_url ouvre alors le Portefeuille, où Payer Voice Studio avec peut passer à ses propres crédits)
403FORBIDDENreason : key_limit_reached, account_gate, scope_not_allowed, cooldown, voice_studio_suspended, wallet_frozen, member_cap_reached, team_payer_unavailable
409CONFLICTreason : quote_exceeds_max_credits, idempotency_conflict, request_in_progress, unit_rendering
413TEXT_TOO_LONGPlus de 5 000 caractères prononcés (max_characters)
422CONTENT_BLOCKED, VOICE_UNAVAILABLE, LANGUAGE_NOT_SUPPORTED_BY_VOICE, INVALID_SCRIPTLe texte ou les voix ne peuvent pas être prononcés tels quels
429RATE_LIMITED, CONCURRENCY_LIMITTrop de requêtes (voir Limites de débit)
503CAPACITY, WARMING_UP, MODERATION_UNAVAILABLE, AI_UNAVAILABLERéessayez après Retry-After secondes
Dernière mise à jour : 20 octobre 2026