Für Entwickler

API-Schnellstart

Schick eine Aufnahme und den Text, zu dem sie passen soll. Du bekommst sechs Werte und eine Aufschlüsselung jedes Wortes und jedes Lautes zurück. Es ist dieselbe Bewertung, die Spellys eigene Apps nutzen.

Deine App sendet
Die Aufnahme, den Text, zu dem sie passen soll, und seine Sprache.
Spelly bewertet
Jeder Laut wird mit dem Laut verglichen, den das Wort braucht.
Du bekommst JSON zurück
Sechs Werte, jedes Wort und jeder Laut, bereit zur Anzeige.

Schnellstart

Jeder Pfad auf dieser Seite folgt auf https://spelly.ch: /api/assess ist https://spelly.ch/api/assess. Schick deinen Schlüssel im Header X-API-Key mit. Zwei vollständige Aufrufe zum Loslegen:

Eine als recording.wav gespeicherte Aufnahme bewerten

curl

curl https://spelly.ch/api/assess \
  -H 'X-API-Key: YOUR_KEY' \
  -F 'reference_text=The weather is lovely' \
  -F language=en-GB \
  -F audio=@recording.wav

Die Modellstimme mit dem Zeitpunkt jedes Lauts und Buchstabens abrufen

curl

curl https://spelly.ch/api/tts/aligned \
  -H 'X-API-Key: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "hello",
    "language": "en-GB",
    "audio_format": "mp3"
  }'

Dein API-Schlüssel

Schick deinen Schlüssel bei jeder Anfrage im Header X-API-Key mit. Du findest ihn in der Operator-Konsole. Bewahre ihn auf deinem Server auf, nie in einer Webseite.

Browser können die API nicht aus deinen Seiten aufrufen: Sie nimmt Cross-Origin-Anfragen nur von Spellys eigenen Websites an, und ein Schlüssel in einer Seite könnte kopiert werden. Ruf sie von deinem Server auf; damit Lernende auf einer Webseite üben, nutze das Widget.

Jede bewertete Aufnahme verbraucht 1 Einheit und jede Modellstimme (/api/tts, /api/tts/aligned, /api/assess/synthesize) 0,5; alle anderen Aufrufe sind kostenlos. Nur erfolgreiche Aufrufe verbrauchen Einheiten: Ein abgelehnter oder fehlgeschlagener Aufruf kostet nichts. Aufnahmen und Stimmen im Widget verbrauchen dieselben Einheiten. Eine kostenlose Testphase hat 100 Einheiten; sind sie aufgebraucht, antworten Aufrufe mit 402 und operator.trialExhausted in detail, daneben remaining und requested.

Ratenlimits

Jede Adresse darf der API im Schnitt 50 Anfragen pro Sekunde schicken und auf einmal bis zu 300 weitere. Darüber antworten Aufrufe mit 429 request.tooManyRequests. Ein kostenloser Testschlüssel darf 60 Anfragen pro Minute schicken. Hat dein Schlüssel ein eigenes Minutenlimit, antworten Aufrufe darüber ebenfalls mit 429.

Antworten mit 429 und 503 tragen einen Header Retry-After: die Sekunden, die du warten sollst, bevor du dieselbe Anfrage erneut schickst.

Weiter

API-Referenz — jeder Endpunkt mit Parametern, Antwort und einem curl-Beispiel.
API-Fehler — jeder Fehlercode und was zu tun ist.