API Pembangun

Terjemahan langsung untuk produk anda sendiri

Satu API untuk terjemahan suara langsung, terjemahan teks, pertuturan dan video dalam 32 bahasa. Kredit prabayar, bayar hanya apa yang anda guna, tiada yuran bulanan.

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

Kosnya

Setiap panggilan dibayar daripada baki prabayar anda. Panggilan yang gagal di pihak kami tidak dicaj.

Terjemahan suara langsung
Strim pertuturan masuk, dapatkan sari kata terjemahan dan suara terjemahan kembali dalam beberapa saat.
USD 0.10 seminit
Sari kata langsung
Strim langsung yang sama, sari kata terjemahan sahaja.
USD 0.05 seminit
Terjemahan teks
Terjemahan semula jadi yang memahami konteks untuk satu teks atau sehingga 50.
USD 10.00 bagi setiap 1 juta aksara
Teks ke pertuturan
Teks dibacakan dengan suara semula jadi, sebagai MP3, WAV atau Opus.
USD 30.00 bagi setiap 1 juta aksara
Pertuturan ke teks
Audio atau video kepada teks dengan cap masa, boleh diterjemah jika mahu.
USD 0.01 seminit
Sari kata video
Video dikembalikan dengan sari kata terjemahan yang dilekatkan, serta fail SRT.
USD 0.20 seminit
Alih suara video
Video dikembalikan dengan alih suara dalam bahasa lain, dengan sari kata jika anda mahu.
USD 0.50 seminit

Pengesahan

Setiap permintaan membawa kunci API anda dalam pengepala Authorization. Kunci dibuat dan dibatalkan dalam papan pemuka anda; setiap satu menggunakan baki yang sama.

  1. Daftar percuma di sponkly.com dan buka Papan pemuka → API Pembangun.
  2. Tambah kredit (dari $10) dan buat kunci API.
  3. Hantar permintaan ke https://api.sponkly.com/v1 dengan Authorization: Bearer <your key>.
Base URL:      https://api.sponkly.com/v1
Authorization: Bearer spk_…

Permintaan bertandatangan

Setiap kunci API disertakan dengan rahsia tandatangan. Apabila anda menandatangani permintaan dengannya, kunci yang dicuri sahaja tidak berguna, permintaan tidak boleh diubah dalam perjalanan dan permintaan yang sama tidak boleh dihantar dua kali. Hidupkan "Wajibkan permintaan bertandatangan" untuk kunci itu dalam papan pemuka anda dan setiap permintaan tanpa tandatangan akan ditolak.

  1. Ambil masa semasa dalam saat Unix dan SHA-256 bagi body tepat yang anda hantar (untuk muat naik fail: bait fail; untuk GET dan soket langsung: body kosong).
  2. Cantumkannya dengan titik sebagai pemisah, mengikut urutan: cap masa, kaedah, laluan bersama rentetan pertanyaan dan hash body.
  3. Buat HMAC-SHA256 bagi teks itu dengan rahsia tandatangan anda, dalam hex huruf kecil.
  4. Hantarnya sebagai X-Sponkly-Signature: v1=<signature>, dengan masa sebagai X-Sponkly-Timestamp. Tandatangan sah selama 5 minit dan untuk satu permintaan sahaja.
  5. Menghantar permintaan yang sama dua kali dalam satu saat (cuba semula pantas atau tinjauan berkala)? Berikan masa dalam milisaat; ia juga diterima dan memastikan setiap tandatangan unik.
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" }));

Pastikan kunci anda selamat

  • Panggil API dari pelayan anda. Jangan sekali-kali letakkan kunci atau rahsia tandatangan dalam halaman web, apl mudah alih atau repositori awam.
  • Wajibkan permintaan bertandatangan untuk setiap kunci dalam pengeluaran.
  • Senaraikan alamat pelayan anda dalam alamat yang dibenarkan bagi kunci, supaya kunci tidak berfungsi dari tempat lain.
  • Tetapkan had perbelanjaan harian bagi setiap kunci, supaya kesilapan atau kebocoran hanya boleh menelan kos yang terhad.
  • Gunakan satu kunci bagi setiap apl atau persekitaran, dan batalkan kunci sebaik sahaja anda rasa ia telah terdedah. Anda juga boleh membuat rahsia tandatangan baharu pada bila-bila masa.
  • Kunci atau tandatangan salah yang berulang dari satu alamat akan menyekat alamat itu selama 15 minit.
POST/v1/translate

Terjemahan teks

Menterjemah satu teks atau senarai sehingga 50 ke mana-mana daripada 32 bahasa. Tinggalkan bahasa sumber untuk dikesan secara automatik.

# 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"])

Medan: text (rentetan atau tatasusunan), target (kod bahasa), source (pilihan), context (pilihan, sehingga 1,000 aksara yang menerangkan tentang teks). Anda membayar bagi setiap aksara yang dihantar.

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

Terjemahan suara langsung

WebSocket untuk pertuturan langsung: hantar audio semasa ia dituturkan dan terima sari kata terjemahan serta, jika diminta, suara terjemahan. Tiga belas bahasa utama diterjemah oleh model pertuturan masa nyata dengan kelewatan kira-kira 1–2 saat; yang lain oleh saluran penstriman kami sendiri.

// 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.
Mesej daripada pelayanMaksudnya
{"t":"ready","engine":"openai|own"}Sesi dibuka; engine menunjukkan laluan terjemahan yang digunakan untuk bahasa ini.
{"t":"partial","text":"…"}Pertuturan yang sedang dikenal pasti (mungkin masih berubah).
{"t":"cap","id","text","done"}Satu baris terjemahan: dipaparkan semasa ia bertambah, muktamad apabila done ialah true.
{"t":"pcm","d":"<base64>","r":24000}Sebahagian suara terjemahan: PCM mono 16-bit pada kadar yang diberi, dalam base64. Mainkan bahagian-bahagian itu berturut-turut.
{"t":"problem","text":"noMinutes"}Baki anda habis; sesi ditutup.

Parameter: source dan target (kod bahasa), voice=0 untuk sari kata sahaja (separuh harga). Hantar audio dalam masa nyata (lebih pantas akan ditolak). Sehingga 10 sesi serentak bagi setiap akaun, 2 jam setiap satu. Anda membayar bagi setiap saat pertuturan yang diterjemah; senyap dan muzik percuma.

POST/v1/speech

Teks ke pertuturan

Menukar teks kepada pertuturan semula jadi dan memulangkan fail audio itu sendiri.

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

Medan: text (sehingga 4,096 aksara), language, voice (female, male, neutral, atau alloy, ash, ballad, coral, echo, fable, onyx, nova, sage, shimmer, verse), format (mp3, wav atau opus), speed (0.5–2). Kosnya ada dalam pengepala X-Sponkly-Cost-Usd.

POST/v1/transcribe

Pertuturan ke teks

Muat naik fail audio atau video (sehingga 25 MB dan 60 minit); dapatkan teks dengan cap masa, serta terjemahannya jika anda minta.

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

Sari kata dan alih suara video

Hantar video sehingga 5 minit dan dapatkannya kembali dalam terjemahan: sari kata dilekatkan, suara terjemahan, atau kedua-duanya, serta fail sari kata dalam kedua-dua bahasa.

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

Medan: target, source (pilihan), dub (true untuk suara terjemahan), subtitles (translated, original, both atau none), content_type (video/mp4 atau video/quicktime), size_bytes, title (pilihan). Anda membayar bagi setiap saat video sebaik panjangnya diketahui. Hasil boleh dimuat turun selama 7 hari.

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

Baki, penggunaan dan bahasa

Semak baki anda dan bila kredit tertua anda tamat tempoh, senaraikan panggilan yang dicaj, dan dapatkan bahasa serta harga semasa.

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 }

Ralat

Ralat dikembalikan sebagai JSON dengan kod tetap dan mesej yang mudah dibaca.

{ "error": { "code": "insufficient_balance", "message": "…" } }
400invalid_text · invalid_target · text_too_long …Ada sesuatu dalam permintaan yang tiada atau tidak dibenarkan; mesej menyatakan apa.
401missing_key · invalid_keyTiada kunci API, atau kunci yang salah atau telah dibatalkan.
402insufficient_balanceBaki anda tidak mencukupi untuk panggilan ini. Tambah kredit di papan pemuka.
429—Terlalu banyak permintaan serentak. Tunggu sebentar dan cuba lagi.
502translation_failed · speech_failed …Ia gagal di pihak kami atau di pihak penyedia. Anda tidak dicaj; cuba lagi.

Had

  • Terjemahan teks: sehingga 50 teks dan 20,000 aksara bagi setiap permintaan, 5,000 bagi setiap teks.
  • Teks ke pertuturan: sehingga 4,096 aksara bagi setiap permintaan.
  • Pertuturan ke teks: fail sehingga 25 MB dan 60 minit.
  • Terjemahan langsung: sehingga 10 sesi serentak bagi setiap akaun, 2 jam setiap satu, audio dalam masa nyata.
  • Video: sehingga 5 minit dan 4 GB, 3 diproses serentak; hasil disimpan 7 hari.
  • Kadar bagi setiap kunci: 300 terjemahan, 120 pertuturan, 60 transkripsi dan 20 video baharu seminit.
  • 32 bahasa: Inggeris, Turki, Jerman, Perancis, Sepanyol, Itali, Portugis, Rusia, Jepun, Korea, Cina, Arab, Hindi, Belanda, Poland, Sweden, Norway, Denmark, Finland, Greek, Czech, Romania, Hungary, Ukraine, Ibrani, Thai, Vietnam, Indonesia, Melayu, Estonia, Parsi dan Catalonia.

Pengebilan

  • Prabayar: tambah kredit dengan kad dari $10; setiap panggilan ditolak daripada baki anda.
  • Yuran pemprosesan kad ditunjukkan dan ditambah semasa pembayaran, jadi seluruh kredit boleh anda gunakan.
  • Kredit boleh digunakan selama 12 bulan selepas dibeli. Ia tidak boleh dikembalikan.
  • Panggilan yang gagal di pihak kami tidak dicaj, dan video yang gagal dibayar balik.
  • Apabila baki anda rendah, kami menghantar e-mel kepada anda; pada sifar, panggilan ditolak dengan 402 sehingga anda menambah kredit.