API бази дикторів – документація v1

Кожен запит вимагає API-ключа в заголовкуX-API-Key. Ми також підтримуємо заголовокAuthorization: Bearer <key>. Ключі мають форматrpm_live_… і призначаються кожній компанії окремо.

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

• Зберігайте ключ на стороні сервера (змінна середовища, конфігурація бекенду) і запитуйте API зі свого власного бекенду.
• Якщо вам потрібно запитувати API з браузера, повідомте нам домени, з яких надходитимуть запити – ми додамо їх до білого списку для вашого ключа.
• Ви можете в будь-який час ротувати ключ: старий одразу перестане працювати, щойно буде згенеровано новий.

GET/v1/languages

Повертає всі мови бази дикторів із кількістю доступних дикторів. Полеslug є ідентифікатором мови, який використовується в інших ендпоінтах.

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

GET/v1/voices

Повертає список дикторів разом із аудіозразками. Без параметраlang повертаються диктори з усіх мов – у цьому випадку ми рекомендуємо пагінацію.

{
  "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 }
}

API не відображає внутрішні теги категоризації RPM Studio. Замість сирих тегів ми надаємо нормалізовані поля express таexclusive, які ви можете безпосередньо використовувати як фільтри чи бейджі в своєму інтерфейсі.

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

Повертає одного диктора в тій самій структурі, що й список, у поліdata. Корисно для підсторінки "картка диктора" на вашому сайті.

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

Node.js / JavaScript

// Увага: зберігайте ключ на своєму сервері, а не в коді браузера.
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"];

• Стандартний ліміт становить 1000 запитів на годину на ключ; для більших реалізацій ми узгоджуємо індивідуальні ліміти.
• У разі перевищення ліміту API повертає статус 429 із заголовком Retry-After.
• Ми рекомендуємо кешувати відповіді на вашій стороні (5–15 хвилин) та оновлювати список дикторів кожні кілька хвилин, а не при кожному відвідуванні користувачем.
• MP3-файли та зображення доставляються через CDN – ви можете посилатися на них напряму, без копіювання на власний сервер.

Помилки повертаються в єдиній структурі з машиночитним кодом та описом, зручним для розробника.

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

• Аудіозразки призначені для презентації голосів кінцевому клієнту – їх не можна використовувати в ефірі чи готових продакшенах.
• Саме замовлення запису ви робите в RPM Studio; після цього ми надаємо продакшн-файли та документацію прав використання.
• Дані API надаються виключно компанії, зазначеній у договорі – ключ не можна передавати третім особам.
• Обсяг полів та ендпоінтів v1 є стабільним; про будь-які зміни ми повідомимо заздалегідь електронною поштою.