Sprecherdatenbank-API – v1 Dokumentation

Jede Anfrage erfordert einen API-Schlüssel im HeaderX-API-Key. Wir unterstützen auch den HeaderAuthorization: Bearer <key>. Schlüssel haben das Formatrpm_live_… und werden jeweils einem Unternehmen zugewiesen.

curl "https://rpm.pl/api/public/v1/voices?lang=polski&gender=f&limit=10" \
  -H "X-API-Key: rpm_live_xxxxxxxxxxxxxxxxxxxxxxxx"

• Speichern Sie den Schlüssel serverseitig (Umgebungsvariable, Backend-Konfiguration) und fragen Sie die API von Ihrem eigenen Backend aus ab.
• Wenn Sie die API aus dem Browser abfragen müssen, teilen Sie uns die Domains mit, von denen die Anfragen kommen werden – wir setzen sie für Ihren Schlüssel auf die Whitelist.
• Sie können den Schlüssel jederzeit rotieren: Der alte funktioniert sofort nicht mehr, sobald ein neuer erzeugt wird.

GET/v1/languages

Liefert alle Sprachen der Sprecherdatenbank mit der Anzahl der verfügbaren Sprecher. Das Feld slug ist der Sprach-Identifikator, der in den anderen Endpunkten verwendet wird.

{
  "data": [
    { "slug": "polski", "label": "Polish", "voices_count": 126 },
    { "slug": "angielski-brytyjski", "label": "English (British)", "voices_count": 31 }
  ],
  "meta": { "total": 45 }
}

GET/v1/voices

Liefert eine Liste von Sprechern zusammen mit Audio-Beispielen. Ohne den Parameter lang werden Sprecher aus allen Sprachen zurückgegeben – in diesem Fall empfehlen wir Paginierung.

{
  "data": [
    {
      "slug": "anna-k",
      "name": "Anna K",
      "language": "polski",
      "language_label": "Polish",
      "gender": "f",
      "price_level": 2,
      "express": true,
      "exclusive": false,
      "availability": "available, turnaround up to 24 h",
      "image_url": "https://media.rpm.pl/voices/polski/anna-k.webp",
      "samples": [
        { "label": "A", "url": "https://media.rpm.pl/audio/polski/anna-k-a.mp3" },
        { "label": "B", "url": "https://media.rpm.pl/audio/polski/anna-k-b.mp3" }
      ],
      "page_url": "https://rpm.pl/bank-glosow/polski"
    }
  ],
  "meta": { "total": 126, "limit": 10, "offset": 0, "count": 10 }
}

Die API zeigt keine internen Kategorisierungs-Tags von RPM Studio an. Anstelle von rohen Tags liefern wir normalisierte Felder express undexclusive, die Sie direkt als Filter oder Badges in Ihrer Benutzeroberfläche verwenden können.

GET/v1/voices/{lang}/{slug}

Liefert einen einzelnen Sprecher in derselben Struktur wie die Liste, innerhalb des Feldes data. Nützlich für eine „Sprecherkarte"-Unterseite auf Ihrer Website.

curl "https://rpm.pl/api/public/v1/voices/polski/anna-k" \
  -H "X-API-Key: rpm_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Node.js / JavaScript

// Hinweis: Bewahren Sie den Schlüssel auf Ihrem Server auf, nicht im Browser-Code.
const res = await fetch(
  "https://rpm.pl/api/public/v1/voices?lang=polski&gender=m",
  { headers: { "X-API-Key": process.env.RPM_API_KEY } }
);
const { data, meta } = await res.json();

data.forEach((voice) => {
  console.log(voice.name, voice.samples[0]?.url);
});

PHP

<?php
$ch = curl_init("https://rpm.pl/api/public/v1/voices?lang=polski");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: " . getenv("RPM_API_KEY")]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$voices = json_decode(curl_exec($ch), true)["data"];

• Das Standardlimit beträgt 1000 Anfragen pro Stunde pro Schlüssel; für größere Implementierungen vereinbaren wir individuelle Limits.
• Bei Überschreitung des Limits liefert die API den Status 429 mit einem Retry-After-Header.
• Wir empfehlen, Antworten auf Ihrer Seite zu cachen (5–15 Minuten) und die Sprecherliste alle paar Minuten statt bei jedem Nutzerbesuch abzurufen.
• MP3-Dateien und Bilder werden über ein CDN ausgeliefert – Sie können sie direkt verlinken, ohne sie auf Ihren eigenen Server zu kopieren.

Fehler werden in einer einheitlichen Struktur zurückgegeben, mit einem maschinenlesbaren Code und einer entwicklerfreundlichen Beschreibung.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Exceeded the limit of 1000 requests per hour."
  }
}

• Audio-Beispiele dienen der Präsentation von Stimmen für den Endkunden – sie dürfen nicht on air oder in fertigen Produktionen verwendet werden.
• Die eigentliche Aufnahme bestellen Sie bei RPM Studio; wir stellen anschließend Produktionsdateien und Nutzungsrechte-Dokumentation bereit.
• API-Daten werden ausschließlich dem im Vertrag genannten Unternehmen zur Verfügung gestellt – der Schlüssel darf nicht weitergegeben werden.
• Der Umfang der Felder und Endpunkte von v1 ist stabil; über etwaige Änderungen informieren wir Sie im Voraus per E-Mail.