API referansı

Her uç nokta, istek ve yanıt şekli, hata kodu ve hız sınırı için tam referans.

Sınırlar ve davranış

Aylık token izni (ücretsiz katman): Model çağrılmadan önce, API tokenleri yaklaşık olarak ceil(content_length / 4) × (number_of_targets + 1) olarak tahmin eder ve sadece free katman için, tahmin kalan aylık izin (varsayılan 100000) aşacaksa isteği 429 / token_limit_reached ile reddeder. Ücretli katmanlar bu ön kontrol tarafından engellenmez; kullanım yine de kaydedilir.

Hız sınırları: Redis yapılandırıldığında, dakikalık sınırlar katmana göre uygulanır: ücretsiz 5, başlangıç 30, büyüme 60, ölçek 120, kurumsal sınırsız. Sınır aşılırsa, yanıt 429 ve error: "rate_limit_reached" olur. Redis yapılandırılmamışsa, hız sınırlandırması atlanır.

Başarılı hız sınırına takılan yanıtlar X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset içerebilir.

GET /health

Kimlik doğrulama yok.

Yanıt 200

{
  "status": "ok",
  "timestamp": "2025-03-23T12:00:00.000Z"
}

GET /languages

Kimlik doğrulama yok.

Desteklenen dillerin kanonik listesini döner (kod, görüntülenen ad, RTL bayrağı). Toplam 43 giriş vardır — 36 temel dil ve 7 bölgesel varyant. Bölgesel varyantlar BCP-47 bölge alt etiketleri kullanır (ör. fr-CA, pt-BR, es-MX). Bu uç noktadan alınan kodlar, çeviri uç noktalarında targets için kabul edilen tek değerlerdir.

Yanıt 200

{
  "languages": [
    { "code": "en", "name": "English", "rtl": false },
    { "code": "ar", "name": "Arabic", "rtl": true }
  ]
}

Canlı liste ayrıca GET /languages ile erişilebilir — aşağıya bakınız.

POST /translate

Authorization: Bearer <api_key> gerektirir.

Tek bir content dizgesini targets içinde listelenen her dile çevirir. Yanıt, istenen dil kodlarının tam olarak anahtar olduğu ve değerlerin çevrilmiş dizgiler olduğu tek bir JSON nesnesidir.

İstek gövdesi

Yanıt 200

{
  "translations": {
    "es": "...",
    "fr": "..."
  },
  "usage": {
    "input_tokens": 120,
    "output_tokens": 340,
    "total_tokens": 460,
    "model": "standard",
    "detected_format": "markdown",
    "detection_confidence": 0.95
  }
}

detected_format ve detection_confidence yalnızca format atlandığında ve otomatik algılama çalıştırıldığında görünür.

Örnek (cURL)

curl -sS -X POST "https://api.usepolylingo.com/v1/translate" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "{\"title\":\"Hello\"}",
    "format": "json",
    "targets": ["fr", "de"]
  }'

Örnek (Python 3)

pip install requests

import os, requests

url = "https://api.usepolylingo.com/v1/translate"
headers = {
    "Authorization": f"Bearer {os.environ['POLYLINGO_API_KEY']}",
    "Content-Type": "application/json",
}
r = requests.post(url, json={
    "content": "<p>Hello <strong>world</strong></p>",
    "format": "html",
    "targets": ["es"],
}, timeout=120)
r.raise_for_status()
print(r.json()["translations"]["es"])

POST /translate/batch

Authorization: Bearer <api_key> gerektirir.

Her öğeyi sıralı olarak işler (öğe başına bir model çağrısı). Herhangi bir öğe başarısız olursa, API 500 döner ve o istek için kısmi sonuç döndürmez.

İstek gövdesi

Yanıt 200

{
  "results": [
    { "id": "welcome", "translations": { "fr": "...", "de": "..." } },
    { "id": "goodbye", "translations": { "fr": "...", "de": "..." } }
  ],
  "usage": {
    "total_tokens": 900,
    "input_tokens": 400,
    "output_tokens": 500,
    "model": "standard"
  }
}

Örnek

curl -sS -X POST "https://api.usepolylingo.com/v1/translate/batch" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "id": "a", "content": "Hello", "format": "plain" },
      { "id": "b", "content": "## Title", "format": "markdown" }
    ],
    "targets": ["es", "it"]
  }'

POST /jobs

Authorization: Bearer <api_key> gerektirir.

Bir çeviri işi kuyruğa alır ve hemen job_id ile yanıt verir. Çeviri arka planda çalışır — içerik boyutuna bakılmaksızın HTTP zaman aşımı riski yoktur. Sonuç için GET /jobs/:id sorgulanmalıdır.

Büyük belgeleri (uzun Markdown, çok sayıda hedef dil) çevirirken, istek süresi HTTP istemci veya proxy zaman aşımınızı aşabilir; bu durumda bu uç noktayı POST /translate yerine kullanın.

İstek gövdesi

Yanıt 202

{
  "job_id": "a1b2c3d4-...",
  "status": "pending",
  "created_at": "2025-03-23T12:00:00.000Z"
}

GET /jobs/:id

Authorization: Bearer <api_key> gerektirir.

POST /jobs ile gönderilen işin durumunu sorgular. Her 5–10 saniyede bir sorgulayın. İşler gönderen kullanıcıya aittir — diğer kullanıcılar 404 alır.

Yanıt (beklemede / işleniyor)

{
  "job_id": "a1b2c3d4-...",
  "status": "pending",
  "created_at": "2025-03-23T12:00:00.000Z",
  "updated_at": "2025-03-23T12:00:00.000Z",
  "completed_at": null,
  "queue_position": 3
}

status pending (işçi bekleniyor) veya processing (işçi talep etti) olabilir. queue_position (1 tabanlı) bu işten önce oluşturulmuş bekleyen veya işlenen iş sayısını gösterir — ilerleme UI için kullanılır. Sayım sorgusu başarısız olursa atlanır.

Yanıt (tamamlandı)

{
  "job_id": "a1b2c3d4-...",
  "status": "completed",
  "created_at": "2025-03-23T12:00:00.000Z",
  "updated_at": "2025-03-23T12:00:02.000Z",
  "completed_at": "2025-03-23T12:00:02.000Z",
  "translations": {
    "es": "...",
    "fr": "..."
  },
  "usage": {
    "input_tokens": 120,
    "output_tokens": 340,
    "total_tokens": 460,
    "model": "standard"
  }
}

Yanıt (başarısız)

{
  "job_id": "a1b2c3d4-...",
  "status": "failed",
  "error": "Model returned invalid JSON"
}

Örnek (JavaScript)

const API = 'https://api.usepolylingo.com/v1'
const headers = {
  'Authorization': `Bearer ${process.env.POLYLINGO_API_KEY}`,
  'Content-Type': 'application/json',
}

// 1. Gönder
const submit = await fetch(`${API}/jobs`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ content: longMarkdown, format: 'markdown', targets: ['de', 'fr'] }),
})
const { job_id } = await submit.json()

// 2. Sorgula
while (true) {
  await new Promise(r => setTimeout(r, 10_000))
  const poll = await fetch(`${API}/jobs/${job_id}`, { headers })
  const job = await poll.json()
  if (job.status === 'completed') { console.log(job.translations); break }
  if (job.status === 'failed')    { throw new Error(job.error) }
  // İsteğe bağlı: ilerlemeyi göster (queue_position 1 tabanlıdır, kuyrukta değilse atlanır)
  if (job.queue_position != null) console.log(`Kuyruk pozisyonu: ${job.queue_position}`)
}

GET /usage

Authorization: Bearer <api_key> gerektirir (standart anahtar sorgusu — yalnızca dahili atlama yolu değil).

Kimliği doğrulanmış kullanıcı için geçerli takvim ayı token kullanımını döner.

Yanıt 200

{
  "period_start": "2025-03-01T00:00:00.000Z",
  "period_end": "2025-03-31T23:59:59.000Z",
  "tokens_used": 12000,
  "tokens_included": 100000,
  "tokens_remaining": 88000,
  "overage_tokens": 0,
  "tier": "free"
}

tokens_included ve tokens_remaining enterprise için nulldır (raporlama için sınırsız izin).

İçerik formatları

Desteklenen format değerleri: plain, markdown, json, html.

Uygulamanızda RTL ve yön

plain ve markdown çıktısı için API yalnızca çevrilmiş metni döner — dir="rtl" veya sarmalayıcı öğeler eklemez. Arapça, İbranice veya Farsça gösterirken UI'nizde metin yönünü ayarlayın (CSS direction, üst öğenin dir özniteliği veya çerçevenizin i18n düzeni).

html formatında, çevrilmiş işaretleme RTL hedefler için uygun yerlerde dir="rtl" içerebilir.

Hata yanıtları

Hatalar mümkün olduğunda JSON'dur:

{
  "error": "invalid_request",
  "message": "İnsan tarafından okunabilir detay"
}

GET /usage Supabase sorgusu başarısız olursa genel bir mesajla 500 dönebilir.