API banku głosów – dokumentacja v1

Każde zapytanie wymaga klucza API przekazanego w nagłówkuX-API-Key. Alternatywnie obsługujemy nagłówekAuthorization: Bearer <klucz>. Klucz ma postaćrpm_live_… i jest przypisany do jednej firmy.

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

• Klucz przechowuj po stronie serwera (zmienna środowiskowa, konfiguracja backendu) i odpytuj API z własnego backendu.
• Jeśli musisz odpytywać API z przeglądarki, zgłoś nam domeny, z których będą wychodzić zapytania – przypiszemy je do klucza.
• Klucz możesz w każdej chwili wymienić: stary przestaje działać natychmiast po wygenerowaniu nowego.

GET/v1/languages

Zwraca wszystkie języki banku głosów wraz z liczbą dostępnych lektorów. Poleslug jest identyfikatorem języka używanym w pozostałych zapytaniach.

{
  "data": [
    { "slug": "polski", "label": "Polski", "voices_count": 126 },
    { "slug": "angielski-brytyjski", "label": "Angielski brytyjski", "voices_count": 31 }
  ],
  "meta": { "total": 45 }
}

GET/v1/voices

Zwraca listę lektorów wraz z próbkami audio. Bez parametrulang zwracane są głosy ze wszystkich języków – w takim wypadku zalecamy stronicowanie.

{
  "data": [
    {
      "slug": "anna-k",
      "name": "Anna K",
      "language": "polski",
      "language_label": "Polski",
      "gender": "f",
      "price_level": 2,
      "express": true,
      "exclusive": false,
      "availability": "dostępny, realizacja do 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 }
}

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

Zwraca pojedynczego lektora w tej samej strukturze co lista, w poludata. Przydatne do podstron typu „karta lektora” w Twoim serwisie.

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

Node.js / JavaScript

// Uwaga: klucz trzymaj na swoim serwerze, nie w kodzie przeglądarki.
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"];

• Standardowy limit to 1000 zapytań na godzinę dla jednego klucza; dla większych wdrożeń ustalamy limit indywidualnie.
• Po przekroczeniu limitu API zwraca status 429 wraz z nagłówkiem Retry-After.
• Zalecamy buforowanie odpowiedzi po swojej stronie (5–15 minut) oraz pobieranie listy głosów raz na kilka minut, a nie przy każdym wejściu użytkownika.
• Pliki MP3 i zdjęcia serwujemy z sieci CDN – możesz linkować je bezpośrednio, bez kopiowania na własny serwer.

Błędy zwracamy w spójnej strukturze, z kodem czytelnym dla maszyny i opisem dla programisty.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Przekroczono limit 1000 zapytań na godzinę."
  }
}

• Próbki audio służą do prezentacji głosów klientowi końcowemu – nie wolno ich wykorzystywać w emisji ani w gotowych produkcjach.
• Nagranie właściwe zamawiasz w RPM Studio; wtedy przekazujemy pliki produkcyjne i dokumentację praw do wykorzystania.
• Dane z API udostępniamy wyłącznie firmie wskazanej w umowie – klucza nie wolno przekazywać dalej.
• Zakres pól i adresy końcowe wersji v1 są stabilne; o ewentualnych zmianach informujemy z wyprzedzeniem e-mailem.