Ein Schlüssel, ein Regal.

Schnellstart

Drei Schritte. Der erste passiert nicht hier, sondern in der Werkbank.

1. Schlüssel holen. Werkbank → Reiter API → Name vergeben, Stimmen anhaken, Schlüssel ausstellen. Der Schlüssel steht genau einmal auf dem Bildschirm. Danach liegt bei uns nur noch sein Abdruck — verloren heißt neu ausstellen.
2. Stimmen nachsehen. GET /api/v1/voices zeigt dein Regal und die Kennungen darin.
3. Sprechen lassen. POST /api/v1/speech mit text und voice.

# 1) Regal ansehen
curl -s https://HOST/api/v1/voices \
  -H "Authorization: Bearer $RIFT_KEY"

# 2) Sprechen lassen — die MP3 landet direkt in der Datei
curl -s https://HOST/api/v1/speech \
  -H "Authorization: Bearer $RIFT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Guten Abend. Der Ton steht.","voice":"VOICE_ID"}' \
  -o ansage.mp3

const KEY = process.env.RIFT_KEY;          // niemals im Frontend
const BASE = "https://HOST";

// 1) Regal ansehen
const { data: voices } = await fetch(`${BASE}/api/v1/voices`, {
  headers: { authorization: `Bearer ${KEY}` },
}).then((r) => r.json());

// 2) Sprechen lassen
const res = await fetch(`${BASE}/api/v1/speech`, {
  method: "POST",
  headers: {
    authorization: `Bearer ${KEY}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    text: "Guten Abend. Der Ton steht.",
    voice: voices[0].id,
  }),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const mp3 = Buffer.from(await res.arrayBuffer());
console.log("Rest heute:", res.headers.get("x-rift-quota-remaining"));

import os, requests

KEY  = os.environ["RIFT_KEY"]              # niemals im Repository
BASE = "https://HOST"
head = {"Authorization": f"Bearer {KEY}"}

# 1) Regal ansehen
voices = requests.get(f"{BASE}/api/v1/voices", headers=head).json()["data"]

# 2) Sprechen lassen
res = requests.post(
    f"{BASE}/api/v1/speech",
    headers=head,
    json={"text": "Guten Abend. Der Ton steht.", "voice": voices[0]["id"]},
    timeout=90,
)
res.raise_for_status()

with open("ansage.mp3", "wb") as f:
    f.write(res.content)

print("Rest heute:", res.headers["X-Rift-Quota-Remaining"])

<?php
$key  = getenv('RIFT_KEY');
$base = 'https://HOST';

$ch = curl_init("$base/api/v1/speech");
curl_setopt_array($ch, [
  CURLOPT_POST           => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => [
    "Authorization: Bearer $key",
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'text'  => 'Guten Abend. Der Ton steht.',
    'voice' => 'VOICE_ID',
  ]),
]);

$mp3    = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status !== 200) { throw new RuntimeException($mp3); }
file_put_contents('ansage.mp3', $mp3);

Authentifizierung

Jede Anfrage außer /health braucht deinen Schlüssel. Zwei gleichwertige Wege:

Authorization: Bearer rvl_7fQ2x9aBc…
X-API-Key: rvl_7fQ2x9aBc…

Ein Schlüssel beginnt immer mit rvl_. Was danach kommt, sind 32 Zufallsbytes — geraten wird da nichts.

Stimmen & Zuteilung

Ein Schlüssel bekommt in der Werkbank entweder alle Stimmen oder eine ausdrückliche Liste. Diese Zuteilung ist die ganze Berechtigungslogik — es gibt keine zweite Ebene.

• Alle Stimmen: auch die, die später dazukommen. Praktisch für eigene Dienste.
• Auswahl: genau die angehakten. Neue Stimmen sind für diesen Schlüssel nicht dabei.
• Was nicht zugeteilt ist, existiert nicht. Eine fremde Kennung beantwortet /speech mit 404 voice_not_found — derselben Antwort wie für eine Kennung, die es nirgends gibt. Aus der Antwort lässt sich das fremde Regal nicht abtasten.
• Die interne Referenz bleibt drinnen. Nach draußen geht nur die kurze Kennung aus /voices, nie die Kennung, mit der die Engine arbeitet.
• Über der Zuteilung steht der Riegel. Jede Stimme trägt in der Werkbank den Schalter öffentlich verwendbar. Steht er auf aus, ist die Stimme für den offenen Zugang nicht vorhanden — auch dann nicht, wenn ein Schlüssel sie ausdrücklich zugeteilt bekommen hat. Sie verschwindet aus /voices und /speech antwortet 404 voice_not_found.

Modelle

Zwei Wege, dieselbe Stimme. Welchen du nimmst, entscheidet das Feld model bei /speech.

"v1" und "v2" sind als Kurzform ebenfalls erlaubt. Ohne model gilt RiftVoiceV1 — bestehende Aufrufe ändern sich also nicht. Ein Name, den es nicht gibt, ergibt 404 model_not_found; still ersetzt wird nie.

Grenzen & Kontingent

Abgerechnet wird die Länge des bereinigten Textes, nicht die der MP3 — bei RiftVoiceV2 mal zwei, Rift 2.1 mal zweieinhalb, siehe Modelle. Der Tageszähler springt um Mitternacht in Berlin zurück; wann genau, steht in jeder Antwort unter quota.resetsAt beziehungsweise im Kopf X-Rift-Quota-Reset.

Fehler

Immer JSON, immer dieselbe Form. Prüfe error.code, nicht den Wortlaut — Texte dürfen sich ändern, Codes nicht.

{
  "error": {
    "type": "rate_limit_error",
    "code": "quota_exhausted",
    "message": "Das Tageskontingent dieses Schluessels ist aufgebraucht.",
    "quota": { "limit": 5000, "used": 5000, "remaining": 0, "resetsAt": "2026-09-04T00:00:00.000Z" },
    "requestId": "rk9f2c1a4b7d0e3",
    "docs": "/api"
  }
}

Zu jeder Antwort gehört eine requestId. Wenn du etwas gemeldet haben möchtest, nenn sie — damit findet sich der Lauf, ohne dass jemand deinen Schlüssel braucht.

Wartung

Wird die Werkstatt geschlossen, ist der Zugang vollständig zu — jeder Pfad unter /api, auch /health und der Bauplan. Es gibt in diesem Zustand keinen Endpunkt, der noch synthetisiert.

{
  "error": {
    "type": "api_error",
    "code": "maintenance",
    "message": "Wartung — der Zugang ist voruebergehend geschlossen.",
    "detail": "Kurze Wartung — gleich wieder da.",
    "retryAfter": 900,
    "requestId": "rk9f2c1a4b7d0e3",
    "docs": "/api"
  }
}

• Status 503, Code maintenance. Behandle das wie service_unavailable: warten, dann erneut.
• Retry-After beachten, wenn ein Ende angekündigt ist. Steht dort nichts, ist das Ende offen — dann mit wachsendem Abstand nachfragen.
• Preflight bleibt beantwortet. Ein Browser bekommt darum eine ehrliche 503 statt eines nichtssagenden CORS-Fehlers.
• Nichts wird abgebucht. Eine abgewiesene Anfrage kostet kein Kontingent.

Antwortköpfe

Aus dem Browser sind diese Köpfe lesbar — sie stehen in Access-Control-Expose-Headers. Cookies gehen dagegen nie mit: die API kennt keine Sitzung.

Schlüssel sicher halten

• Nur auf dem Server. Umgebungsvariable oder Geheimnisverwaltung — nicht ins Repository, nicht ins Bundle, nicht in ein Log.
• Ein Schlüssel je Zweck. Getrennt für Produktion, Test und jeden Partner. Dann trifft ein Widerruf genau eine Sache.
• So wenig Regal wie nötig. Ein Schlüssel für eine Stimme kann auch nur diese eine.
• Kontingent als Bremse. Das Tageslimit ist die Obergrenze des Schadens, wenn ein Schlüssel doch einmal abhandenkommt.
• Ablaufdatum für Gäste. Wer nur drei Wochen etwas bauen soll, braucht keinen Schlüssel, der ewig gilt.
• Bei Verdacht neu ausstellen. Einstellungen und Zuteilung bleiben, nur das Geheimnis ist ein anderes.

Konsole

Echte Anfragen an diese Instanz. Der Schlüssel bleibt in diesem Tab und wird nirgendwo gespeichert — ein Neuladen leert das Feld.

Die Konsole ruft dieselben Endpunkte auf wie dein Code. Was hier funktioniert, funktioniert dort.