Authentifizierung

Ein Authorization: Bearer sk-echo-...-Header bei jeder Anfrage. Der Schlüssel wird nur einmal angezeigt, wenn Sie ihn erstellen: Speichern Sie ihn. Wenn Sie ihn verlieren, widerrufen Sie ihn und erstellen Sie einen anderen.

Einen API-Schlüssel auf bestimmte IPs beschränken

Jeder API-Schlüssel kann auf die Adressen beschränkt werden, von denen aus seine Nutzung sinnvoll ist. Wenn Ihre Integration auf einem Server mit fester IP lebt, ist ein gestohlener Schlüssel außerhalb davon nichts wert.

Es wird in Ihrem Konto konfiguriert, in der Spalte Erlaubte IPs jedes Schlüssels. Einzelne Adressen und Netzwerke werden akzeptiert:

203.0.113.7, 198.51.100.0/24, 192.0.2.10

Leer gelassen, funktioniert der Schlüssel von überall, was das Standardverhalten ist.

Eine Anfrage von einer IP, die nicht auf der Liste steht, erhält 403 mit dem Code ip_not_allowed und, im Body, die IP, die wir gesehen haben — was genau das ist, was Sie brauchen, um sie hinzuzufügen, falls Sie eine ausgelassen haben:

{
  "error": "ip_not_allowed",
  "message": "This API key is restricted to a list of IP addresses and this request does not come from one of them",
  "client_ip": "203.0.113.55"
}

Die Beschränkung deckt jeden authentifizierten Endpunkt ab, einschließlich /v1/usage/last. Wer einen Schlüssel stiehlt, will ihn nicht immer ausgeben; manchmal genügt es, zu sehen, wie viel sein Besitzer ausgibt.

Analyse in derselben Anfrage

Eine Transkription kann die Stimmanalyse mitbringen, ohne das Audio erneut hochzuladen. Sie werden im Query-String angefordert, durch Kommas getrennt:

curl https://api.uttera.ai/v1/audio/transcriptions?extras=sentiment,profile,diarize \
  -H "Authorization: Bearer $UTTERA_API_KEY" \
  -F file=@recording.m4a \
  -F model=whisper-1

Alle drei laufen parallel über dasselbe Audio, sodass das Anfordern von dreien fast so lange dauert wie das Anfordern von einem. Jede wird separat berechnet, und nur, wenn sie läuft: Wenn eine Analyse fehlschlägt, kommt die Transkription trotzdem an, und die Antwort trägt ein errors-Array, das sagt, welche fehlte — und diese wird nicht berechnet.

Für sentiment mit Detail pro Segment oder dimensional (Valenz, Erregung, Dominanz) verwenden Sie den eigenständigen Endpunkt /v1/audio/sentiment: In extras ist es immer die globale Ebene.

Formate und Sprachen

Eingangsaudio: wav, mp3, flac, ogg, opus, aiff, m4a und webm. webm ist das, was ein Browser aufzeichnet, und m4a das, was ein Telefon aufzeichnet, sodass beide so, wie sie kommen, für die Transkription funktionieren.

Ausgangsaudio (das response_format der Sprache): wav, mp3, opus, flac und pcm. pcm ist rohes PCM ohne Header, daher bietet die Web-App es nicht an — ein Browser kann es nicht abspielen — und wenn Sie es über die API verwenden, müssen Sie Ihrem Decoder die vier Parameter mitteilen, weil die Datei sie nicht trägt:

Die Rate ist die native jeder Stimme und wird nicht umgetastet: HD erzeugt mit 48 kHz und wird so geliefert. Das Einzige, was sich zwischen beiden unterscheidet, ist die Rate; sie mit der falschen zu decodieren klingt nicht schlechter, es klingt mit doppelter oder halber Geschwindigkeit. Mit wav, flac oder opus gilt das nicht: Die Datei deklariert es selbst.

# standard voice
ffmpeg -f s16le -ar 24000 -ac 1 -i voice.pcm voice.wav
# HD voice
ffmpeg -f s16le -ar 48000 -ac 1 -i voice.pcm voice.wav

Jeder andere Wert von response_format gibt 422 mit der gültigen Liste zurück.

Größe: bis zu 150 MB pro Anfrage und 2 Stunden Audio. Ein unkomprimiertes 2-Stunden-WAV passt nicht: Senden Sie langes Audio komprimiert. Das Detail steht in Größe und Dauer.

Transkription: erkennt die Sprache automatisch und deckt die ab, die Whisper unterstützt.

Sprache: hängt von der Engine ab, und der Unterschied ist groß. Die Standardstimme (tts-1) spricht die neun in der Tabelle unten. Die hochwertige Stimme (tts-1-hd) spricht rund 30 — neben diesen neun Deutsch, Russisch, Polnisch, Niederländisch, die nordischen Sprachen, Griechisch, Türkisch, Arabisch, Koreanisch und mehrere südostasiatische, unter anderem — und die Sprache muss nicht angegeben werden: Sie wird aus dem Text erschlossen. Es wird in Drei Stimmen, nicht zwei erklärt.

Übersetzung: ~50 Textsprachen. Die Kette synthetisiert mit der Standardstimme, sodass es mit Sprache diese neun sind:

Stimmenkatalog

Die sechs OpenAI-kompatiblen Stimmen, verfügbar mit model: tts-1:

alloy · echo · fable · nova · onyx · shimmer

Der Katalog ist deutlich länger, und er wird über die API abgefragt, statt hier hineinkopiert zu werden, sodass das, was Sie lesen, genau das ist, was gerade tatsächlich ausgeliefert wird.

GET /v1/audio/voices

curl https://api.uttera.ai/v1/audio/voices \
  -H "Authorization: Bearer $UTTERA_API_KEY"

{
  "voices": ["adam", "alex", "alex-pt", "alice", "alloy", …],
  "catalog": [
    {"name": "adam",    "language": "en"},
    {"name": "alex",    "language": "es"},
    {"name": "alex-pt", "language": "pt"},
    …
  ]
}

voices ist die reine Namensliste, zum Befüllen eines Dropdowns; catalog ergänzt die Sprache jeder Stimme. language kann null sein bei Stimmen, die zu keiner bestimmten Sprache gehören. Eine Stimme, die nicht auf dieser Liste steht, liefert 422 zurück.

Credits

Jeder Dienst berechnet, was er verbraucht. Dies sind die aktuellen Koeffizienten:

Wie sich jeder Dienst zusammensetzt

Ein echtes Beispiel

Eine 40-minütige Aufnahme (2.424 s), ins Englische übersetzt mit Sprachausgabe:

transcription     79.22   2,424.5 s x 0.032673
speech            43.18   2,055.8 s x 0.021004   (English comes out ~15% shorter)
translation      193.96   2,424.5 s x 0.080000
                 ──────
                 316.36 credits

Tarife und Grenzen

Die Credits erneuern sich an Ihrem Abo-Datum, nicht am 1. des Monats. Wenn Sie in einen kleineren Tarif wechseln, behalten Sie die bereits bezahlten Credits bis zum Ende des Zeitraums.

Dieselbe Tabelle wird als JSON und ohne Schlüssel ausgeliefert, damit ein Programm – oder ein Agent, der sich selbst konfiguriert – die Grenzen lesen kann, bevor sich überhaupt jemand anmeldet:

curl https://api.uttera.ai/v1/plans

{"plans": {"free": {"price_eur_per_month": 0, "credits_per_month": 500,
  "max_concurrent": 1, "rate_limits": {"stt": 1, "tts": 1, "sfx": 0,
  "intelligence": 0}, "summary_allowed": false, "voice_clone_allowed": false, …}, …}}

Es ist dieselbe Quelle, die die Tabelle oben füllt: Ändert sich etwas, ändern sich beide zugleich.

Grenzen pro Sekunde

Jede Antwort trägt X-RateLimit-Remaining-Second und X-Credits-Remaining-Monthly, damit Sie nicht raten müssen.

Maximale Größe und Dauer

Lange Aufnahmen: wie die Zusammenfassung damit umgeht

Eine lange Aufnahme passt nicht am Stück in den Kontext des Modells. Statt einen Teil davon zusammenzufassen, teilen wir sie auf, fassen jedes Stück zusammen und führen es dann zusammen – und die Zusammenführung ist keine Zusammenfassung von Zusammenfassungen, die zweimal Informationen verlieren würde: Das Modell wird angewiesen, die Stücke zu ordnen und zu kombinieren und dabei jede Zahl, jedes Datum und jeden Namen zu erhalten.

Die Zusammenfassung hat also keine eigene, kürzere Grenze: Was Sie transkribieren können, können Sie zusammenfassen. Von Anfang bis Ende gemessen an einer vierstündigen Aufnahme mit Ton, Sprecherprofil und Diarisierung: sechs Minuten, vollständig, mit Anfang und Ende beide vorhanden.

Sollte eine Zusammenfassung je gekürzt zurückkommen, sagt die Antwort das in truncated. Das ist nichts, was Sie sehen sollten, und wir sagen es Ihnen lieber, als Ihnen eine gekürzte Zusammenfassung zu übergeben, die sich wie eine vollständige liest.

Zwei Stunden müssen in 150 MB passen

Die beiden Grenzen sind unabhängig, und Sie müssen beide einhalten. Für volle zwei Stunden bedeutet das, unter 175 kbps zu bleiben:

Für Sprache verliert ein mp3 mit 64 kbps nichts, was für uns zählt, und lässt Ihnen reichlich Spielraum. Wenn Sie unkomprimiertes wav senden, rechnen Sie damit, dass zwei Stunden nicht passen.

Text zu Sprache: die Grenze hängt von der Stimme ab

Es gibt keine einheitliche Grenze, weil die beiden Stimmen von unterschiedlicher Maschinerie erzeugt werden:

Standardstimme (tts-1). Sie kann auf zwei Arten angefordert werden:

• Vollständige Antwort (/v1/audio/speech): Wir liefern das ganze Audio, sobald es fertig ist. Weil alles zugleich existieren muss, liegt die Obergrenze bei 250.000 Zeichen – ungefähr vier bis fünf Stunden Sprache. Wir sagen bewusst „ungefähr": Wie viel Audio aus einem Zeichen wird, hängt stark vom Text ab, und an echter Prosa gemessen reicht es von 12,6 bis 17,5 Zeichen pro Sekunde. Die Obergrenze liegt auf dem Text, nicht auf der Dauer.
• Streaming (/v1/audio/speech/stream): Wir senden das Audio, während es erzeugt wird. Hier gibt es keine Längengrenze, weil sich nichts anhäuft.

Für eine lange Erzählung ist Streaming nach wie vor der bessere Weg. Sie hören das Ergebnis binnen Sekunden, statt auf das Ende zu warten, und nichts muss in eine einzige Antwort passen.

Hochwertige und geklonte Stimme (tts-1-hd). Die Obergrenze liegt bei 2.000 Zeichen pro Anfrage, etwa zweieinhalb Minuten Sprache. Das ist erheblich weniger, und es ist eine Beschränkung des Modells hinter dieser Stimme, keine kommerzielle Entscheidung. Bei dieser Stimme hilft Streaming bei langem Text nicht: Verwenden Sie sie in Blöcken von ein paar tausend Zeichen und verketten Sie diese.

Fehler

Ihren Verbrauch prüfen

Die Berechnung erfolgt, nachdem die Antwort an Sie gesendet wurde, sie kommt also nicht darin enthalten. Um genau herauszufinden, was Sie eine Anfrage gekostet hat:

GET /v1/usage/last
GET /v1/usage/last?endpoint=/v1/summarize

Es liefert die berechneten Credits und die Aufschlüsselung nach Stufe zurück:

{
  "endpoint": "/v1/summarize",
  "credits": 108.978,
  "breakdown": { "stt": 3.1255, "diarize": 2.0029,
                 "profile": 0.1946, "llm": 103.655 },
  "audio_seconds": 95.66,
  "input_tokens": 2776, "output_tokens": 1230
}

Es behält die letzten zehn Abrechnungen für eine Stunde. Es dient zum Nachschauen im Moment, nicht als Abrechnungshistorie.

Wie lange es dauert

Gemessene Zahlen, keine Versprechen. Sie schwanken mit dem Knoten, der Sie bedient, und der Last zu diesem Zeitpunkt:

Was wirklich richtig eingestellt sein muss, ist das Timeout Ihres Clients: Der Server hält die Verbindung bis zu 7200 Sekunden offen, und der häufigste Fehler bei der Integration ist ein Client mit einem Standardwert von 30 Sekunden, der Aufträge abbricht, die einwandfrei liefen. Das wird in Integration erklärt.

Versionierung und Änderungen

Was Sie heute integrieren, muss morgen weiterlaufen. Das ist die Selbstverpflichtung:

Damit das etwas bedeutet, müssen wir sagen, was als inkompatibel gilt und was nicht:

Daraus folgt die praktische Regel für Ihren Code: Ignorieren Sie Felder, die Sie nicht erkennen, statt zu scheitern, wenn Sie ihnen begegnen. Ein Client, der abstürzt, weil die Antwort einen neuen Schlüssel trägt, wird von selbst kaputtgehen, ohne dass irgendjemand etwas kaputtgemacht hat.

Preise sind ein gesonderter Fall: Sie sind nicht die Schnittstelle, aber sie sind Ihre Rechnung. Eine Erhöhung der Koeffizienten wird mit dreißig Tagen Vorlauf angekündigt und wird nicht auf einen bereits bezahlten Zyklus angewandt. Eine Senkung gilt, sobald es sie gibt.

Dienststatus

Wenn etwas schiefgeht, ist das Erste zu wissen, ob es an Ihnen oder an uns liegt.

GET https://api.uttera.ai/health antwortet ohne Schlüssel und sagt, ob die API läuft. Es ist die Prüfung, die Sie automatisieren können.

curl -s https://api.uttera.ai/health

Jede Antwort trägt außerdem einen X-Request-Id-Header. Bewahren Sie ihn auf, wenn etwas fehlschlägt: Mit dieser Kennung können wir Ihnen genau sagen, was mit Ihrer Anfrage passiert ist, und ohne sie beginnt das Gespräch damit, zu rekonstruieren, welche es war.

Schreiben Sie uns bei jedem Vorfall mit der X-Request-Id, der ungefähren Uhrzeit und dem, was Sie erwartet hatten.

In Arbeit

Dinge, die Leute anfragen, die Sinn ergeben und die es noch nicht gibt. Wir führen sie hier auf, weil herauszufinden, dass etwas nicht existiert, nachdem man es integriert hat, schlimmer ist als es jetzt zu wissen:

Wenn eines davon Sie blockiert, sagen Sie es uns: Was Kunden anfragen, entscheidet die Reihenfolge.