NueForm

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

POST/api/v1/voice

Erzeugt 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)

textstring

speak: die Wörter, die gelesen werden

voicestring

Eine nv_…-Stimme aus Stimmen auflisten. Für speak erforderlich; in einem script die Stimme für Zeilen ohne Sprecher-Tag

linesarray

script: strukturierte Zeilen, jeweils {"speaker", "voice", "text"} oder eine Pause {"pause_ms": 800} (bis 10.000)

scriptstring

script: das Mehrstimmen-Format, eine Zeile pro Sprecher: [Maya] Did you hear that?

castarray

script: eine Stimme für jeden getaggten Sprecher, [{"speaker": "Maya", "voice": "nv_…"}]

auto_convertboolean

Ein eingefügtes Drehbuch oder einen Chatverlauf (MAYA: Hi) zuerst ins Mehrstimmen-Format umwandeln. Kostenlos, innerhalb eines Tageslimits

auto_castboolean

Jedem Sprecher ohne Stimme eine Stimme zuweisen. Kostenlos, innerhalb eines Tageslimits. Sende language für ein Skript, das nicht auf Englisch ist

languagestring

Ein Sprachname oder -code ("es", "Spanish"). Standard: die eigene Sprache der Stimme

qualitystring

"standard" (Standard), "studio" oder "phone". Gleicher Preis

speednumber

0,85 bis 1,15 (Standard 1)

formatstring

"mp3" (Standard), "wav", "ogg_opus" oder "mulaw_8k"

max_creditsinteger

Die Anfrage ablehnen (409, nichts berechnet), wenn sie mehr kosten würde

reuseboolean

Standard true: Auf eine identische Anfrage aus den letzten 30 Tagen wird mit jenem Audio für 0 Credits geantwortet

saveboolean

true behält das Audio, bis du es löschst. Standard: nach 30 Tagen gelöscht

retake_ofstring

Eine Generierung neu erzeugen (siehe Retakes)

titlestring

Ihr Titel in deiner Library

Antwortfelder

idstring

Die Generierung (gen_…)

statusstring

"ready", "rendering" (202: wird noch erzeugt), "partial" (einige Zeilen sind fehlgeschlagen und kosten nichts) oder "failed"

audioobject or null

url (sende deinen API-Schlüssel mit), format, sample_rate, duration_seconds, retained_until

creditsobject

estimated, charged (was diese Anfrage berechnet hat) und remaining

linesarray

Nur script: speaker, voice, text, status, start_ms, end_ms und credits jeder Zeile

retakes_remaininginteger

Verbleibende kostenlose Retakes für diesen Clip

reusedboolean

Das Audio einer identischen früheren Anfrage, für 0 Credits

Codebeispiele

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 -

Dieser Text hat 75 gesprochene Zeichen und kostet daher 30 Credits (75 × 0,4).

Antwort-Header

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

JSON-Antwort

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" }
}

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

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"
}

Oder das Mehrstimmen-Format

json
{
  "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

POST/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

charactersinteger

Gesprochene Zeichen: das, was berechnet wird

creditsinteger

Genau das, was die Anfrage berechnen würde

seconds_estimatednumber

Ungefähr, wie lang das Audio wird

balanceinteger

Dein aktuelles Guthaben

enoughboolean

Dein Guthaben (und das Monatslimit des Schlüssels, falls vorhanden) reicht dafür

Beispiel

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" }
}

Sprache streamen

POST/api/v1/voice/stream

Sendet 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

voicestring

Eine nv_…-Stimme aus Stimmen auflisten

textstring

Die 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)

languagestring

Ein Sprachname oder -code. Standard: die eigene Sprache der Stimme

qualitystring

"standard" (Standard; "phone" bei mulaw_8k), "studio" oder "phone". Gleicher Preis

max_creditsinteger

Die Anfrage ablehnen (409, nichts berechnet), wenn sie mehr kosten würde

saveboolean

true behält die gespeicherte Kopie, bis du sie löschst. Standard: nach 30 Tagen gelöscht

titlestring

Ihr Titel in deiner Library

speed, Skripte, retake_of und reuse gibt es bei einem Stream nicht (400, reason: "not_on_stream").

Codebeispiele

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

Dieser Text hat 35 gesprochene Zeichen und kostet daher 14 Credits (35 × 0,4).

Antwort-Header

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

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_of nennt 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 CONFLICT mit reason: "idempotency_conflict";
  • solange die erste Anfrage noch läuft, 409 CONFLICT mit reason: "request_in_progress" und Retry-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:

HeaderBedeutung
NueForm-Generation-IdDie Generierung (gen_…)
NueForm-Credits-EstimatedDer Preis, der der Anfrage genannt wurde
NueForm-Credits-ChargedWas 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-RemainingDein Guthaben danach
NueForm-Rate-CardDie Preisliste, nach der berechnet wurde
NueForm-Retakes-RemainingVerbleibende kostenlose Retakes für diesen Clip
NueForm-Audio-DurationDie Länge des Audios in Sekunden
Idempotent-ReplayedMit einem Idempotency-Key: ob dies eine frühere Anfrage beantwortet
NueForm-Audio-Format, NueForm-Audio-Encoding, NueForm-Audio-Sample-Rate, NueForm-Audio-ChannelsDas Audio eines Streams: Format, Kodierung, Abtastrate und Kanäle
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-ResetDie Anfragen dieses Schlüssels in dieser Minute (siehe Rate Limits)

Stimmen auflisten

GET/api/v1/voice/voices

Die 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"

languagestring

Ein Sprachname oder -code

genderstring

Zum Beispiel "female"

qstring

Namen, Stile und Bezeichnungen durchsuchen

featuredboolean

true: nur hervorgehobene Standardstimmen

Antwort

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 }
}

Stimme löschen

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

Lö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

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

Generierungen auflisten

GET/api/v1/voice/generations

Deine Generierungen, die neuesten zuerst. Blättere mit meta.next_cursor weiter.

Query-Parameter

limitinteger

1 bis 100 (Standard 20)

cursorstring

next_cursor der vorherigen Seite

sourcestring

Nur die über "api", "studio", "mcp" oder "app" erzeugten

Antwort

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

Generierung abrufen

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

Eine Generierung, bei einem Skript mit ihren lines. Hier ist credits.charged das, was sie insgesamt gekostet hat, nach jeder automatischen Gutschrift.

Audio herunterladen

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

Das 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

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

Lö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

GET/api/v1/credits

Das 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

balanceinteger

Credits, die du jetzt ausgeben kannst (10.000 Credits = 1 $)

approxstring

Das Guthaben in Dollar

keyobject

monthly_credit_limit dieses Schlüssels (null = keins), spent_this_month, paused und resets_at (der 1., UTC)

voice_apiobject

credits_per_character (0,4), wie gerundet wird, und dass Schätzungen kostenlos sind

rate_cardobject

Jeder Preis, nach Aktion

Antwort

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" }
}

Preise

WasCreditsIn Dollar
Sprache über die Voice-API0,4 pro gesprochenem Zeichen, jede Spracheetwa 0,04 $ pro 1.000 Zeichen
Eine Schätzung0kostenlos
Ein wiederverwendeter Clip (reuse)0kostenlos
Ein Retake0 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:

StatuscodeWann
402INSUFFICIENT_CREDITSDein 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)
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_LONGMehr als 5.000 gesprochene Zeichen (max_characters)
422CONTENT_BLOCKED, VOICE_UNAVAILABLE, LANGUAGE_NOT_SUPPORTED_BY_VOICE, INVALID_SCRIPTDer Text oder die Stimmen können so nicht gesprochen werden
429RATE_LIMITED, CONCURRENCY_LIMITZu viele Anfragen (siehe Rate Limits)
503CAPACITY, WARMING_UP, MODERATION_UNAVAILABLE, AI_UNAVAILABLENach Retry-After Sekunden erneut versuchen
Zuletzt aktualisiert: 20. Oktober 2026