Voice-API
Erzeuge Sprache aus deinem eigenen Code mit den Stimmen von Voice Studio: eine Stimme oder ein ganzes Skript, 0,4 Credits pro gesprochenem Zeichen in jeder Sprache, mit einer kostenlosen Schätzung vorab.
Erzeuge Sprache aus deinem eigenen Code mit NueSpeak Apex, denselben Stimmen wie in Voice Studio. Anfragen verbrauchen Credits aus deinem NueForm-Guthaben: 0,4 Credits pro gesprochenem Zeichen (etwa 0,04 $ pro 1.000 Zeichen) in jeder Sprache, einmal pro Anfrage auf einen ganzen Credit aufgerundet. Schätzungen sind kostenlos.
Alle Anfrage- und Antwort-Bodys verwenden Feldnamen in snake_case. Stimmen werden mit nv_…-IDs benannt, Generierungen mit gen_…-IDs.
Voice-Schlüssel funktionieren in jedem Tarif, sobald dein Konto einen ersten Credit-Kauf getätigt hat (oder einen bezahlten Tarif nutzt) und seine E-Mail-Adresse bestätigt ist. Siehe Voice-API-Schlüssel.
Sprache erzeugen
/api/v1/voiceErzeugt das Audio und antwortet, sobald es fertig ist (synchron, höchstens 5.000 gesprochene Zeichen pro Anfrage). Sende Accept: audio/mpeg (oder audio/wav, audio/ogg, audio/basic, audio/*), um das Audio selbst zu erhalten; sonst ist die Antwort JSON mit einer authentifizierten audio.url.
Die Credits werden beim Start der Anfrage abgebucht. Zeilen, die fehlschlagen, werden automatisch gutgeschrieben, und nichts, was mit einem Fehler endet, wird berechnet. Eine Anfrage, die berechnet wurde, endet nie mit einem Fehler: Ist ihr Audio nicht rechtzeitig fertig, antwortet sie mit 202 und einem Location-Header. Hol das Audio dort ab, statt die Anfrage erneut zu senden.
Anfrage-Body
modestring"speak" (eine Stimme liest text), "script" (mehrere Stimmen) oder "estimate" (siehe Kosten schätzen)
textstringspeak: die Wörter, die gelesen werden
voicestringEine nv_…-Stimme aus Stimmen auflisten. Für speak erforderlich; in einem script die Stimme für Zeilen ohne Sprecher-Tag
linesarrayscript: strukturierte Zeilen, jeweils {"speaker", "voice", "text"} oder eine Pause {"pause_ms": 800} (bis 10.000)
scriptstringscript: das Mehrstimmen-Format, eine Zeile pro Sprecher: [Maya] Did you hear that?
castarrayscript: eine Stimme für jeden getaggten Sprecher, [{"speaker": "Maya", "voice": "nv_…"}]
auto_convertbooleanEin eingefügtes Drehbuch oder einen Chatverlauf (MAYA: Hi) zuerst ins Mehrstimmen-Format umwandeln. Kostenlos, innerhalb eines Tageslimits
auto_castbooleanJedem Sprecher ohne Stimme eine Stimme zuweisen. Kostenlos, innerhalb eines Tageslimits. Sende language für ein Skript, das nicht auf Englisch ist
languagestringEin Sprachname oder -code ("es", "Spanish"). Standard: die eigene Sprache der Stimme
qualitystring"standard" (Standard), "studio" oder "phone". Gleicher Preis
speednumber0,85 bis 1,15 (Standard 1)
formatstring"mp3" (Standard), "wav", "ogg_opus" oder "mulaw_8k"
max_creditsintegerDie Anfrage ablehnen (409, nichts berechnet), wenn sie mehr kosten würde
reusebooleanStandard true: Auf eine identische Anfrage aus den letzten 30 Tagen wird mit jenem Audio für 0 Credits geantwortet
savebooleantrue behält das Audio, bis du es löschst. Standard: nach 30 Tagen gelöscht
retake_ofstringEine Generierung neu erzeugen (siehe Retakes)
titlestringIhr Titel in deiner Library
Antwortfelder
idstringDie Generierung (gen_…)
statusstring"ready", "rendering" (202: wird noch erzeugt), "partial" (einige Zeilen sind fehlgeschlagen und kosten nichts) oder "failed"
audioobject or nullurl (sende deinen API-Schlüssel mit), format, sample_rate, duration_seconds, retained_until
creditsobjectestimated, charged (was diese Anfrage berechnet hat) und remaining
linesarrayNur script: speaker, voice, text, status, start_ms, end_ms und credits jeder Zeile
retakes_remainingintegerVerbleibende kostenlose Retakes für diesen Clip
reusedbooleanDas Audio einer identischen früheren Anfrage, für 0 Credits
Codebeispiele
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 -
Dieser Text hat 75 gesprochene Zeichen und kostet daher 30 Credits (75 × 0,4).
Antwort-Header
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
JSON-Antwort
{
"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" }
}
Skripte
Ein Skript spricht mehrere Stimmen in einer Audiodatei. Sende strukturierte lines (ganz ohne Parsing) oder ein script im Mehrstimmen-Format mit seinem cast. Pausen ({"pause_ms": 800} oder (pause 2s) in einem Skript) kosten nichts; berechnet werden nur gesprochene Zeichen.
Die Antwort enthält zusätzlich lines: wo jede Zeile im Audio beginnt und endet, ihren Status und was ihre Zeichen ergeben (credits, als Dezimalzahl). Die Anfrage wird einmal berechnet und aufgerundet. Eine fehlgeschlagene Zeile zeigt "credits": 0 und kostet nichts.
Mit auto_convert wird ein eingefügtes Drehbuch oder ein Chatverlauf zuerst umgewandelt; mit auto_cast bekommt jeder Sprecher ohne Stimme eine.
Anfragebeispiel
{
"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"
}
Oder das Mehrstimmen-Format
{
"mode": "script",
"script": "[Maya] Did you hear that?\n[Leo] Hear what?\n(pause 1s)\n[Maya] Exactly. Nothing.",
"auto_cast": true
}
Kosten schätzen
/api/v1/voice"mode": "estimate" nimmt denselben Body wie speak oder script und antwortet mit den genauen Kosten, ohne etwas zu erzeugen. Das ist kostenlos und zählt nicht gegen deine Generierungslimits (bis zu 300 pro Minute und Schlüssel).
Antwortfelder
charactersintegerGesprochene Zeichen: das, was berechnet wird
creditsintegerGenau das, was die Anfrage berechnen würde
seconds_estimatednumberUngefähr, wie lang das Audio wird
balanceintegerDein aktuelles Guthaben
enoughbooleanDein Guthaben (und das Monatslimit des Schlüssels, falls vorhanden) reicht dafür
Beispiel
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."}'
{
"data": {
"object": "voice.estimate",
"characters": 75,
"credits": 30,
"seconds_estimated": 4.8,
"balance": 48760,
"enough": true
},
"meta": { "rate_card": "1" }
}
Sprache streamen
/api/v1/voice/streamSendet das Audio, während es entsteht, damit deine App nach etwa einer Sekunde zu spielen beginnt, statt auf den ganzen Clip zu warten: ein Agent, ein Voicebot, eine Vorlesefunktion. Eine Stimme liest text. Bei einer warmen Sprach-Engine kommt das erste Audio meist nach 1–2 Sekunden, egal wie lang der Text ist.
Der Preis ist der von Sprache erzeugen: 0,4 Credits pro gesprochenem Zeichen, einmal pro Anfrage aufgerundet und abgebucht, wenn der Stream beginnt. Ein Stream nimmt bis zu etwa 200 Sekunden Sprache an: etwa 3.100 Zeichen Englisch, weniger in Sprachen, die langsamer gesprochen werden (längerer Text ergibt 413 TEXT_TOO_LONG mit max_characters). Für längeren Text sendest du mehrere Streams oder nutzt POST /api/v1/voice.
Vor dem ersten Byte ist jeder Fehler ein normaler Fehler und kostet nichts: Scheitert die Sprach-Engine vor jedem Audio, wird die Abbuchung gutgeschrieben (500, oder 503 WARMING_UP mit Retry-After, während die Engine startet). Nach dem ersten Byte kann sich der Status nicht mehr ändern, deshalb hört ein Stream, der unterwegs scheitert, vor seinem Ende auf: Dein HTTP-Client meldet einen unvollständigen Body. Mit NueForm-Generation-Id und Generierung abrufen siehst du die gespeicherte Kopie und was sie gekostet hat. Wenn du auflegst, wird der Stream trotzdem fertig erzeugt und gespeichert, und es gibt keine Gutschrift.
Jeder Stream wird außerdem als Generierung gespeichert: Er liegt in deiner Library, und Audio herunterladen liefert ihn, normalisiert wie jeder Clip.
Streamen oder /voice? Streame, wenn jemand darauf wartet, es zu hören (Agents, Voicebots, Vorlesen). Nutze POST /api/v1/voice für Dateien, Skripte mit mehreren Stimmen, speed, Retakes und Schätzungen. MCP-Tools streamen nicht: Sie erzeugen Audio auf dem /voice-Weg.
Anfrage-Body
voicestringEine nv_…-Stimme aus Stimmen auflisten
textstringDie Wörter, die gelesen werden
formatstring"mp3" (Standard, für Browser), "pcm_24k" (rohes 16-Bit-Little-Endian-Mono-PCM mit 24.000 Hz, für Agents) oder "mulaw_8k" (8 kHz G.711 μ-law, für Telefonie; "ulaw_8000" geht auch)
languagestringEin Sprachname oder -code. Standard: die eigene Sprache der Stimme
qualitystring"standard" (Standard; "phone" bei mulaw_8k), "studio" oder "phone". Gleicher Preis
max_creditsintegerDie Anfrage ablehnen (409, nichts berechnet), wenn sie mehr kosten würde
savebooleantrue behält die gespeicherte Kopie, bis du sie löschst. Standard: nach 30 Tagen gelöscht
titlestringIhr Titel in deiner Library
speed, Skripte, retake_of und reuse gibt es bei einem Stream nicht (400, reason: "not_on_stream").
Codebeispiele
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
Dieser Text hat 35 gesprochene Zeichen und kostet daher 14 Credits (35 × 0,4).
Antwort-Header
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
Retakes
Sende {"mode": "speak", "retake_of": "gen_…"}, um eine Generierung mit denselben Wörtern, Stimmen, derselben Sprache, Qualität und Geschwindigkeit neu zu erzeugen. Mit retake_of gehen nur mode, format, max_credits und save.
- Kostenlos zweimal innerhalb von 24 Stunden nach der Generierung, solange die kostenlosen Retakes des Schlüssels in diesem Monat höchstens ein Viertel der Zeichen ausmachen, die ihm in diesem Monat berechnet wurden. Ein kostenloser Retake behält dieselbe
gen_…-ID. - Sonst ist es eine neue Generierung, berechnet wie jede Anfrage (0,4 Credits pro Zeichen), und
retake_ofnennt die Generierung, die neu aufgenommen wurde.
Sende "mode": "estimate" mit retake_of, um es vorher zu sehen: Die Antwort sagt "free": true oder was es kosten würde.
Idempotenz
Sende bei speak- und script-Anfragen einen Idempotency-Key-Header (1–255 Zeichen, zum Beispiel eine UUID), dann kann eine Wiederholung nie doppelt berechnen:
- derselbe Schlüssel mit demselben Body antwortet erneut mit dem, was die erste Anfrage erzeugt hat, ohne zu berechnen (
Idempotent-Replayed: true,NueForm-Credits-Charged: 0); - derselbe Schlüssel mit einem anderen Body ergibt
409 CONFLICTmitreason: "idempotency_conflict"; - solange die erste Anfrage noch läuft,
409 CONFLICTmitreason: "request_in_progress"undRetry-After.
Schlüssel werden 24 Stunden lang gespeichert, pro API-Schlüssel.
Bei einem Stream antwortet derselbe Schlüssel mit demselben Body mit JSON: der Generierung, die die erste Anfrage erzeugt hat (sie wird nicht noch einmal gestreamt).
Antwort-Header
Jede Antwort sagt, was sie gekostet hat:
| Header | Bedeutung |
|---|---|
NueForm-Generation-Id | Die Generierung (gen_…) |
NueForm-Credits-Estimated | Der Preis, der der Anfrage genannt wurde |
NueForm-Credits-Charged | Was diese Anfrage berechnet hat, nach jeder automatischen Gutschrift (0 für eine Schätzung, einen wiederverwendeten Clip, einen kostenlosen Retake, eine Wiederholung und jeden Fehler) |
NueForm-Credits-Remaining | Dein Guthaben danach |
NueForm-Rate-Card | Die Preisliste, nach der berechnet wurde |
NueForm-Retakes-Remaining | Verbleibende kostenlose Retakes für diesen Clip |
NueForm-Audio-Duration | Die Länge des Audios in Sekunden |
Idempotent-Replayed | Mit einem Idempotency-Key: ob dies eine frühere Anfrage beantwortet |
NueForm-Audio-Format, NueForm-Audio-Encoding, NueForm-Audio-Sample-Rate, NueForm-Audio-Channels | Das Audio eines Streams: Format, Kodierung, Abtastrate und Kanäle |
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset | Die Anfragen dieses Schlüssels in dieser Minute (siehe Rate Limits) |
Stimmen auflisten
/api/v1/voice/voicesDie Standardstimmen von NueForm, dann deine eigenen und die Stimmen deiner Teams, jeweils mit ihrer nv_…-ID, ihrer Sprache, einer kostenlosen Vorschau und ihrem Sprechtempo. Kostenlos.
Query-Parameter
sourcestring"all" (Standard), "stock" oder "mine"
languagestringEin Sprachname oder -code
genderstringZum Beispiel "female"
qstringNamen, Stile und Bezeichnungen durchsuchen
featuredbooleantrue: nur hervorgehobene Standardstimmen
Antwort
{
"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 }
}
Stimme löschen
/api/v1/voice/voices/:idLöscht eine deiner Stimmen endgültig: ihr Sample, ihre Prompts und ihre Vorschau, dann die Stimme selbst. Credits werden nicht erstattet. Solange Formulare oder Telefonnummern die Stimme noch nutzen, lautet die Antwort 409 CONFLICT mit reason: "voice_in_use" und wie viele; sende ?replacement=nv_…, um sie vorher auf eine andere Stimme umzustellen.
Antwort
{
"data": {
"id": "nv_9LmQ2xT4aPe7vK3sW",
"object": "voice",
"deleted": true,
"switched": { "forms": 2, "numbers": 1 },
"forms_to_republish": 1
}
}
Generierungen auflisten
/api/v1/voice/generationsDeine Generierungen, die neuesten zuerst. Blättere mit meta.next_cursor weiter.
Query-Parameter
limitinteger1 bis 100 (Standard 20)
cursorstringnext_cursor der vorherigen Seite
sourcestringNur die über "api", "studio", "mcp" oder "app" erzeugten
Antwort
{
"data": [
{ "id": "gen_2cH4kXyQ9vLmNp3Rs", "object": "voice.generation", "status": "ready", "credits": { "charged": 30 } }
],
"meta": { "next_cursor": null, "has_more": false }
}
Generierung abrufen
/api/v1/voice/generations/:idEine Generierung, bei einem Skript mit ihren lines. Hier ist credits.charged das, was sie insgesamt gekostet hat, nach jeder automatischen Gutschrift.
Audio herunterladen
/api/v1/voice/generations/:id/audioDas Audio selbst, gestreamt mit deinem API-Schlüssel (Byte-Bereiche werden unterstützt). ?format= ist mp3 (Standard), wav, ogg_opus oder mulaw_8k. Ogg/Opus und 8-kHz-μ-law werden beim ersten Abruf erzeugt: Ein 202 heißt „nach Retry-After Sekunden erneut fragen“. Kostenlos.
Generierung löschen
/api/v1/voice/generations/:idLöscht die Generierung und ihr Audio endgültig. Credits werden nicht erstattet. Eine Generierung, die noch erzeugt wird, antwortet mit 409 CONFLICT und reason: "still_rendering".
Credits abfragen
/api/v1/creditsDas Guthaben, aus dem dein Schlüssel bezahlt, der Monat des Schlüssels und die Preisliste. Nur lesend, mit einem Voice-Schlüssel oder einem Schlüssel mit Vollzugriff.
Antwortfelder
balanceintegerCredits, die du jetzt ausgeben kannst (10.000 Credits = 1 $)
approxstringDas Guthaben in Dollar
keyobjectmonthly_credit_limit dieses Schlüssels (null = keins), spent_this_month, paused und resets_at (der 1., UTC)
voice_apiobjectcredits_per_character (0,4), wie gerundet wird, und dass Schätzungen kostenlos sind
rate_cardobjectJeder Preis, nach Aktion
Antwort
{
"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" }
}
Preise
| Was | Credits | In Dollar |
|---|---|---|
| Sprache über die Voice-API | 0,4 pro gesprochenem Zeichen, jede Sprache | etwa 0,04 $ pro 1.000 Zeichen |
| Eine Schätzung | 0 | kostenlos |
Ein wiederverwendeter Clip (reuse) | 0 | kostenlos |
| Ein Retake | 0 zweimal innerhalb von 24 Stunden (Fair Use), danach 0,4 pro Zeichen |
Credits kommen aus Paketen (ab 5 $ für 50.000 Credits) und verfallen nie. Ein Schlüssel kann ein monatliches Credit-Limit haben: Sobald er so viel ausgegeben hat, erhalten seine Sprach- und Löschanfragen bis zum 1. 403 FORBIDDEN mit reason: "key_limit_reached" (abrufen und herunterladen, was er erzeugt hat, kann er weiterhin), und deine anderen Schlüssel funktionieren weiter. Anfragen werden mit den Credits bezahlt, die der Inhaber des Schlüssels in der Wallet unter Voice Studio bezahlen mit gewählt hat: seinen eigenen, außer er hat ein Team gewählt. Ein Team, das nicht zahlen kann, wird nie durch seine eigenen Credits ersetzt: Die Anfrage erhält 403 FORBIDDEN mit reason: "team_payer_unavailable" oder, sobald er sein monatliches Limit als Mitglied erreicht hat, reason: "member_cap_reached", und nichts wird berechnet.
Fehler
Jeder Fehler verwendet das Standard-Fehlerformat, und nichts, was mit einem Fehler endet, wird berechnet. Die häufigsten:
| Status | code | Wann |
|---|---|---|
| 402 | INSUFFICIENT_CREDITS | Dein Guthaben reicht für die Anfrage nicht (credits_required, credits_available, top_up_url; payer: "team", wenn das Team, mit dem der Inhaber des Schlüssels bezahlt, nicht genug hat: Dann öffnet top_up_url die Wallet, wo sich Voice Studio bezahlen mit auf die eigenen Credits umstellen lässt) |
| 403 | FORBIDDEN | reason: key_limit_reached, account_gate, scope_not_allowed, cooldown, voice_studio_suspended, wallet_frozen, member_cap_reached, team_payer_unavailable |
| 409 | CONFLICT | reason: quote_exceeds_max_credits, idempotency_conflict, request_in_progress, unit_rendering |
| 413 | TEXT_TOO_LONG | Mehr als 5.000 gesprochene Zeichen (max_characters) |
| 422 | CONTENT_BLOCKED, VOICE_UNAVAILABLE, LANGUAGE_NOT_SUPPORTED_BY_VOICE, INVALID_SCRIPT | Der Text oder die Stimmen können so nicht gesprochen werden |
| 429 | RATE_LIMITED, CONCURRENCY_LIMIT | Zu viele Anfragen (siehe Rate Limits) |
| 503 | CAPACITY, WARMING_UP, MODERATION_UNAVAILABLE, AI_UNAVAILABLE | Nach Retry-After Sekunden erneut versuchen |