API для розробників

Переклад у реальному часі для вашого продукту

Один API для голосового перекладу в реальному часі, перекладу тексту, озвучення та відео 32 мовами. Передплачений баланс, оплата лише за використане, без щомісячної плати.

curl https://api.sponkly.com/v1/translate \
  -H "Authorization: Bearer $SPONKLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Merhaba dünya", "target": "en"}'

{
  "translation": "Hello world",
  "target": "en",
  "characters": 13,
  "cost_usd": "0.000130"
}

Скільки це коштує

Кожен виклик оплачується з вашого передплаченого балансу. Виклик, що не вдався з нашого боку, не тарифікується.

Голосовий переклад у реальному часі
Передавайте мовлення потоком і за кілька секунд отримуйте перекладені субтитри та перекладений голос.
0,10 USD за хвилину
Субтитри в реальному часі
Той самий потік у реальному часі, лише перекладені субтитри.
0,05 USD за хвилину
Переклад тексту
Природний переклад з урахуванням контексту — одного тексту або до 50.
10,00 USD за 1 млн символів
Озвучення тексту
Текст, озвучений природним голосом, у форматі MP3, WAV або Opus.
30,00 USD за 1 млн символів
Розпізнавання мовлення
Аудіо чи відео в текст із часовими мітками, за бажанням з перекладом.
0,01 USD за хвилину
Субтитри до відео
Відео з вбудованими перекладеними субтитрами, а також файли SRT.
0,20 USD за хвилину
Дубляж відео
Відео, озвучене іншою мовою, за бажанням із субтитрами.
0,50 USD за хвилину

Автентифікація

Кожен запит містить ваш ключ API в заголовку Authorization. Ключі створюються й відкликаються в особистому кабінеті; усі вони витрачають один баланс.

  1. Зареєструйтеся безкоштовно на sponkly.com і відкрийте Особистий кабінет → API для розробників.
  2. Поповніть баланс (від $10) і створіть ключ API.
  3. Надсилайте запити на https://api.sponkly.com/v1 із заголовком Authorization: Bearer <your key>.
Base URL:      https://api.sponkly.com/v1
Authorization: Bearer spk_…

Підписані запити

Кожен ключ API має секрет підпису. Якщо підписувати ним запити, один лише викрадений ключ нічого не дасть, запит не можна змінити дорогою, а той самий запит не можна надіслати двічі. Увімкніть «Вимагати підписані запити» для ключа в особистому кабінеті, і кожен непідписаний запит буде відхилено.

  1. Візьміть поточний час у секундах Unix і SHA-256 саме того тіла, яке надсилаєте (для завантаження файлу — байти файлу; для GET і живого сокета — порожнє тіло).
  2. Об’єднайте їх крапками в такому порядку: мітка часу, метод, шлях із рядком запиту та хеш тіла.
  3. Обчисліть HMAC-SHA256 цього тексту своїм секретом підпису в шістнадцятковому вигляді малими літерами.
  4. Надішліть його як X-Sponkly-Signature: v1=<signature>, а час — як X-Sponkly-Timestamp. Підпис дійсний 5 хвилин і лише для одного запиту.
  5. Надсилаєте той самий запит двічі протягом секунди (швидкий повтор або опитування)? Передавайте час у мілісекундах — це теж приймається, і кожен підпис лишається унікальним.
X-Sponkly-Timestamp: 1792693200
X-Sponkly-Signature: v1=hex( HMAC-SHA256( signing_secret,
    "1792693200" + "." + "POST" + "." + "/v1/translate" + "." + hex(SHA-256(body)) ) )
// Node.js 18+
import crypto from "node:crypto";

async function sponkly(method, path, body) {
  const raw = body === undefined ? "" : JSON.stringify(body);
  const ts = Math.floor(Date.now() / 1000).toString();
  const hash = crypto.createHash("sha256").update(raw).digest("hex");
  const sig = crypto.createHmac("sha256", process.env.SPONKLY_SIGNING_SECRET)
    .update(`${ts}.${method}.${path}.${hash}`).digest("hex");
  const res = await fetch("https://api.sponkly.com" + path, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.SPONKLY_KEY}`,
      "Content-Type": "application/json",
      "X-Sponkly-Timestamp": ts,
      "X-Sponkly-Signature": `v1=${sig}`,
    },
    body: raw || undefined,
  });
  return res.json();
}

console.log(await sponkly("POST", "/v1/translate", { text: "Merhaba dünya", target: "en" }));

Бережіть свої ключі

  • Викликайте API зі свого сервера. Ніколи не розміщуйте ключ чи секрет підпису на вебсторінці, у мобільному застосунку або в публічному репозиторії.
  • Вимагайте підписані запити для кожного ключа в продакшені.
  • Додайте адреси своїх серверів до дозволених адрес ключа, щоб він більше ніде не працював.
  • Установіть денний ліміт витрат для кожного ключа, щоб помилка чи витік коштували лише обмежену суму.
  • Використовуйте окремий ключ для кожного застосунку чи середовища й відкличте ключ, щойно запідозрите, що його розкрито. Також можна будь-коли створити новий секрет підпису.
  • Повторні неправильні ключі чи підписи з однієї адреси блокують цю адресу на 15 хвилин.
POST/v1/translate

Переклад тексту

Перекладає один текст або список до 50 текстів будь-якою з 32 мов. Не вказуйте мову оригіналу, щоб її було визначено автоматично.

# One text, or up to 50: "text": ["Good morning", "Thank you"]
curl https://api.sponkly.com/v1/translate \
  -H "Authorization: Bearer $SPONKLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Bugün hava çok güzel.", "target": "en", "source": "tr"}'
// JavaScript (Node 18+, Deno, Bun)
const res = await fetch("https://api.sponkly.com/v1/translate", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SPONKLY_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ text: ["Good morning", "Thank you"], target: "de" }),
});
const { translations } = await res.json(); // [{ text: "Guten Morgen" }, { text: "Danke" }]
# Python
import os, requests
r = requests.post("https://api.sponkly.com/v1/translate",
    headers={"Authorization": f"Bearer {os.environ['SPONKLY_KEY']}"},
    json={"text": "How are you?", "target": "ja", "context": "A message to a hotel guest"})
print(r.json()["translation"])

Поля: text (рядок або масив), target (код мови), source (необов’язково), context (необов’язково, до 1000 символів про те, про що текст). Оплата за кожен надісланий символ.

WSwss://api.sponkly.com/v1/live?source=en&target=tr

Голосовий переклад у реальному часі

WebSocket для мовлення в реальному часі: надсилайте аудіо під час мовлення й отримуйте перекладені субтитри та, на запит, перекладений голос. Тринадцять основних мов перекладає мовленнєва модель реального часу із затримкою близько 1–2 секунд; решту — наш власний потоковий конвеєр.

// Node.js (npm i ws). Send 16 kHz mono 16-bit PCM in ~100 ms frames, in real time.
import WebSocket from "ws";
const ws = new WebSocket("wss://api.sponkly.com/v1/live?source=en&target=tr&voice=1", {
  headers: { Authorization: `Bearer ${process.env.SPONKLY_KEY}` },
});
ws.on("message", (raw) => {
  const e = JSON.parse(raw);
  if (e.t === "cap" && e.done) console.log("caption:", e.text);   // a translated line
  if (e.t === "pcm") play(Buffer.from(e.d, "base64"), e.r);      // translated voice, 24 kHz PCM
});
microphone.on("data", (frame) => ws.send(frame));               // binary frames

// Browsers cannot set headers: new WebSocket(url, ["sponkly-key", key]). Never put your key in a public page —
// open the socket from your server, or from an app only your own team uses.
Повідомлення від сервераЩо воно означає
{"t":"ready","engine":"openai|own"}Сесію відкрито; engine показує, який шлях перекладу обслуговує цю мову.
{"t":"partial","text":"…"}Мовлення, що розпізнається саме зараз (воно ще може змінитися).
{"t":"cap","id","text","done"}Перекладений рядок: показується в міру наростання, остаточний, коли done дорівнює true.
{"t":"pcm","d":"<base64>","r":24000}Фрагмент перекладеного голосу: 16-бітний моно PCM із зазначеною частотою дискретизації, у base64. Відтворюйте фрагменти один за одним без пауз.
{"t":"problem","text":"noMinutes"}Баланс вичерпано; сесія закривається.

Параметри: source і target (коди мов), voice=0 лише для субтитрів (за півціни). Надсилайте аудіо в реальному часі (швидше — відхиляється). До 10 одночасних сесій на акаунт, по 2 години кожна. Оплата за кожну секунду перекладеного мовлення; тиша й музика безкоштовні.

POST/v1/speech

Озвучення тексту

Перетворює текст на природне мовлення й повертає сам аудіофайл.

curl https://api.sponkly.com/v1/speech \
  -H "Authorization: Bearer $SPONKLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Merhaba, hoş geldiniz.", "language": "tr", "voice": "female", "format": "mp3"}' \
  --output welcome.mp3

Поля: text (до 4096 символів), language, voice (female, male, neutral або alloy, ash, ballad, coral, echo, fable, onyx, nova, sage, shimmer, verse), format (mp3, wav або opus), speed (0.5–2). Вартість указано в заголовку X-Sponkly-Cost-Usd.

POST/v1/transcribe

Розпізнавання мовлення

Завантажте аудіо- чи відеофайл (до 25 МБ і 60 хвилин) й отримайте текст із часовими мітками та, на запит, його переклад.

curl https://api.sponkly.com/v1/transcribe \
  -H "Authorization: Bearer $SPONKLY_KEY" \
  -F [email protected] \
  -F language=tr \
  -F translate_to=en

{ "text": "…", "language": "tr", "duration_seconds": 182.4,
  "segments": [{ "start": 0.0, "end": 4.2, "text": "…" }],
  "translation": { "text": "…", "target": "en" }, "cost_usd": "0.030430" }
POST/v1/videos

Субтитри та дубляж відео

Надішліть відео до 5 хвилин і отримайте його перекладеним: із вбудованими субтитрами, перекладеним голосом або з обома, а також файли субтитрів обома мовами.

# 1. Ask for a video: dubbed into Turkish, with Turkish subtitles
curl https://api.sponkly.com/v1/videos -H "Authorization: Bearer $SPONKLY_KEY" -H "Content-Type: application/json" \
  -d '{"target": "tr", "dub": true, "subtitles": "translated", "content_type": "video/mp4", "size_bytes": 48211022}'
# → { "id": "…", "upload": { "method": "PUT", "url": "https://…", "headers": { "Content-Type": "video/mp4" } } }

# 2. Upload the file to that link
curl -X PUT -H "Content-Type: video/mp4" --data-binary @talk.mp4 "<upload.url>"

# 3. Start it, then poll until "status": "ready"
curl -X POST https://api.sponkly.com/v1/videos/<id>/start -H "Authorization: Bearer $SPONKLY_KEY"
curl https://api.sponkly.com/v1/videos/<id> -H "Authorization: Bearer $SPONKLY_KEY"
# → { "status": "ready", "cost_usd": "0.500000",
#     "result": { "video_url": "https://…", "subtitles": { "tr": "https://…srt", "en": "https://…srt" } } }

Поля: target, source (необов’язково), dub (true для перекладеного голосу), subtitles (translated, original, both або none), content_type (video/mp4 або video/quicktime), size_bytes, title (необов’язково). Оплата за кожну секунду відео, щойно стане відома його тривалість. Результати доступні для завантаження 7 днів.

GET/v1/balance · /v1/usage · /v1/languages

Баланс, використання та мови

Перевіряйте баланс і термін дії найстарішого поповнення, переглядайте список оплачених викликів, отримуйте перелік мов і актуальні ціни.

curl https://api.sponkly.com/v1/balance -H "Authorization: Bearer $SPONKLY_KEY"
# → { "balance_usd": "48.213400", "next_expiry": "2027-10-22T09:12:00.000Z" }

curl "https://api.sponkly.com/v1/usage?limit=20" -H "Authorization: Bearer $SPONKLY_KEY"
# → { "data": [{ "product": "live", "units": 312.5, "unit": "second", "cost_usd": "0.520834", … }], "has_more": false }

Помилки

Помилки повертаються у форматі JSON зі сталим кодом і зрозумілим повідомленням.

{ "error": { "code": "insufficient_balance", "message": "…" } }
400invalid_text · invalid_target · text_too_long …У запиті чогось бракує або щось не дозволено; у повідомленні сказано, що саме.
401missing_key · invalid_keyНемає ключа API, або ключ неправильний чи відкликаний.
402insufficient_balanceБаланс не покриває цей виклик. Поповніть баланс в особистому кабінеті.
429—Забагато запитів одночасно. Зачекайте трохи й повторіть.
502translation_failed · speech_failed …Збій стався на нашому боці або в провайдера. Кошти не списано; повторіть запит.

Обмеження

  • Переклад тексту: до 50 текстів і 20 000 символів на запит, 5000 на текст.
  • Озвучення тексту: до 4096 символів на запит.
  • Розпізнавання мовлення: файли до 25 МБ і 60 хвилин.
  • Переклад у реальному часі: до 10 одночасних сесій на акаунт, по 2 години кожна, аудіо в реальному часі.
  • Відео: до 5 хвилин і 4 ГБ, до 3 в обробці одночасно; результати зберігаються 7 днів.
  • Ліміти на ключ за хвилину: 300 перекладів, 120 озвучень, 60 розпізнавань і 20 нових відео.
  • 32 мови: англійська, турецька, німецька, французька, іспанська, італійська, португальська, російська, японська, корейська, китайська, арабська, гінді, нідерландська, польська, шведська, норвезька, данська, фінська, грецька, чеська, румунська, угорська, українська, іврит, тайська, в’єтнамська, індонезійська, малайська, естонська, перська та каталанська.

Оплата

  • Передплата: поповнюйте баланс карткою від $10; кожен виклик списується з балансу.
  • Комісію за обробку картки показано й додано під час оплати, тож уся сума поповнення залишається вам.
  • Поповнення можна використати протягом 12 місяців після оплати. Кошти не повертаються.
  • Виклик, що не вдався з нашого боку, не тарифікується, а кошти за відео, яке не вдалося створити, повертаються на баланс.
  • Коли баланс закінчується, ми надсилаємо вам лист; на нулі виклики відхиляються з кодом 402, доки ви не поповните баланс.