Equalang API referansı ve hızlı başlangıç

Equalang'ı yönetim arka ucunuza veya iş akışınıza entegre ettiğinizde metni anında çevirebilir ya da desteklenen yerlerde özgün düzeni koruyarak belge, ses ve video gibi dosyaların tamamını işleyebilirsiniz.

Bu rehber, cURL ve Python ile dosya çeviri iş akışı için hızlı bir başlangıç sunar; ardından API'nin 10 genel endpoint'inin eksiksiz referansını verir.

Kimlik doğrulama ve standart yanıt

Equalang API'si https://equalang.com/v1 adresinde sunulur. API anahtarınızı HTTP Authorization başlığında göndererek her isteğin kimliğini doğrulayın:

Authorization: Bearer el_your_api_key_here

API anahtarınız doğru kapsamlara (scope) sahip olmalıdır (örneğin işler için translations:document, metin için translations:text, doğrudan dosya indirmek için files:read).

Standart yanıt zarfı: Başarılı tüm JSON yanıtları standart bir üst düzey yapı kullanır. Kısa tutmak için aşağıdaki yapısal örnekler bazı önemsiz alanları atlar, ancak tamamen geçerli JSON nesneleri olmayı sürdürür. Gösterilen kimlikler, URL'ler ve bakiye sayıları yalnızca örnektir — kendi yanıtlarınızda dönen gerçek değerleri kullanın.

{
  "code": "OK",
  "message": "ok",
  "data": {},
  "request_id": "req_example_id"
}

Hızlı başlangıç: asenkron dosya çevirisi

Bir belgenin tamamını işlemek asenkron bir iş akışı gerektirir: işi başlatmak için dosyayı yükleyin, durumunu sorgulayın ve sonucu indirin. Kendi dosyanızı kullanabilir ya da denemek için örnek dosyamız olan supply-confirmation.zh-CN.docx dosyasını indirebilirsiniz.

Yöntem 1: cURL ile

Önce API anahtarınızı dışa aktarın (bunu https://equalang.com/api-keys adresinde oluşturabilirsiniz):

export EQUALANG_API_KEY="el_your_api_key_here"

1. Dosyayı yükleyin ve işi başlatın

Dosyayı doğrudan gönderin. API gerekli kredileri ayırır ve bir job_id döndürür. Zaman aşımı oluşursa yinelenen işleri önlemek için benzersiz bir Idempotency-Key (örneğin bir UUID) ekleyin. Aynı gönderimi yeniden denemeniz gerekirse bu anahtarı tekrar kullanın; yeni görevler için yenisini oluşturun. (Çalıştırmadan önce yerel olarak report.docx adında bir dosyanız bulunduğundan emin olun ya da kodda adı değiştirin.)

curl --fail-with-body -X POST "https://equalang.com/v1/jobs/translate" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -H "Idempotency-Key: a-unique-uuid-here" \
  -F "file=@report.docx" \
  -F "target_language=en"

Sonraki adımda kullanmak için job_id değerini yanıtın data nesnesinden çıkarın. Örneklerdeki eski kimlikleri kopyalamayın.

2. İş durumunu sorgulayın

İlerlemeyi izlemek için job_id değerinizi kullanın. İstekler arasında Retry-After başlığının önerdiği süre kadar bekleyin. finished değeri true olduğunda sorgulamayı bırakın.

curl --fail-with-body "https://equalang.com/v1/jobs/your_actual_job_id" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

3. Sonucu indirin

Durum SUCCEEDED olduğunda yanıt geçici bir download_url içerir. Bu URL geçici imza yetkilendirmesi kullandığı için, oradan indirirken API Bearer belirtecinizi göndermeniz gerekmez (ve göndermemelisiniz). HTTP hatalarında sessizce başarısız olması için -f gibi bir bayrak kullanın; böylece hata sayfasını dosyanız diye kaydetmezsiniz.

curl -f -o report_translated.docx "https://example.com/download/your_temporary_signature_url"

Yöntem 2: Python (requests) ile

Not: requests kitaplığı gerekir (pip install requests).

import os
import time
import requests

API_KEY = os.environ.get("EQUALANG_API_KEY")
# Provide a stable key for the same request, change it for new tasks
IDEMPOTENCY_KEY = os.environ.get("IDEMPOTENCY_KEY", "your-unique-uuid-here")

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Idempotency-Key": IDEMPOTENCY_KEY
}
BASE_URL = "https://equalang.com/v1"

# 1. Create Job
# Ensure you have a local file named report.docx before running
with open("report.docx", "rb") as f:
    files = {"file": f}
    data = {"target_language": "en"}
    response = requests.post(
        f"{BASE_URL}/jobs/translate",
        headers=HEADERS,
        files=files,
        data=data,
        timeout=30
    )
    response.raise_for_status()
    job_id = response.json()["data"]["job_id"]
    print(f"Job created: {job_id}")

# 2. Poll Job
while True:
    res = requests.get(f"{BASE_URL}/jobs/{job_id}", headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
    res.raise_for_status()
    job_data = res.json()["data"]

    if job_data["finished"]:
        if job_data["status"] == "SUCCEEDED":
            download_url = job_data["download_url"]
            print(f"Success! Downloading result...")

            # 3. Download Result (No API key needed for the temporary URL)
            dl_res = requests.get(download_url, timeout=30)
            dl_res.raise_for_status()
            with open("report_translated.docx", "wb") as out:
                out.write(dl_res.content)
            print("Download complete.")
        else:
            print(f"Job ended with status: {job_data['status']}")
        break

    retry_after = int(res.headers.get("Retry-After", 5))
    time.sleep(retry_after)

Gelişmiş kullanım senaryolarında (örneğin önce maliyet tahminini kontrol etmek veya kaybolan sorgulama durumlarını kurtarmak için) gelişmiş betiğimizi indirebilirsiniz: translate_file.py.

---

Endpoint referansı

Aşağıda 10 genel endpoint'in ayrıntıları ve yük (payload) yapısı örnekleri yer alıyor.

Desteklenen tam dil kodları için (örneğin zh-CN, en) OpenAPI şemasındaki DocumentLanguage ve TextLanguage numaralandırmalarına ya da geliştirici rehberine bakın. auto kodu yalnızca source_language içindir.

1. Metni çevir

POST /v1/text/translate

Metin dizelerini senkron olarak çevirir. Metinler yalnızca başarıyla çevrildiklerinde ücretlendirilir. Belirli bir dil otomatik olarak algılanmadıysa detected_source_language değeri null olur.

curl --fail-with-body -X POST "https://equalang.com/v1/text/translate" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"texts": ["您的订单已发货。"], "target_language": "en"}'

{
  "code": "OK",
  "message": "ok",
  "data": {
    "translations": [
      {
        "translated_text": "Your order has been shipped.",
        "detected_source_language": null,
        "error": null
      }
    ],
    "usage": {
      "credits_charged": 0.07
    }
  },
  "request_id": "dd0b35ce1b52474faad670a33a9fc62d"
}

2. Fiyat teklifi için dosya yükle

POST /v1/files

Çeviriye başlamadan önce olası en yüksek maliyeti göstermeniz gerekiyorsa dosyayı buraya yükleyin. Bu endpoint bir file_id ve quote (gereken kredi) döndürür.

curl --fail-with-body -X POST "https://equalang.com/v1/files" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -F "file=@report.docx"

{
  "code": "OK",
  "message": "ok",
  "data": {
    "file_id": "a132cf83-e641-41a3-9220-dfefb0e3d2a6",
    "quote": {
      "translate": 0.59,
      "transcribe": null
    }
  },
  "request_id": "e81b9f386ace4a82b63dc292c9cff669"
}

3. Belge çeviri işi oluştur

POST /v1/jobs/translate

Asenkron bir çeviri işi oluşturur. file (multipart), file_url veya file_id kabul eder.

# Using a previously uploaded file_id
curl --fail-with-body -X POST "https://equalang.com/v1/jobs/translate" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "a132cf83-e641-41a3-9220-dfefb0e3d2a6", "target_language": "en"}'

{
  "code": "OK",
  "message": "ok",
  "data": {
    "job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
    "status": "INIT",
    "credits_reserved": 0.59
  },
  "request_id": "36c7dc43855b4e9eae553e7fd656788c"
}

4. Transkripsiyon işi oluştur

POST /v1/jobs/transcribe

Bir ses veya video dosyasındaki konuşmayı çevirmeden, zaman damgalı altyazı olarak çıkarıp döndürür.

curl --fail-with-body -X POST "https://equalang.com/v1/jobs/transcribe" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -F "file=@interview.mp3" \
  -F 'options={"output_formats": ["srt", "txt"]}'

{
  "code": "OK",
  "message": "ok",
  "data": {
    "job_id": "b1a23c45-1234-5678-90ab-cdef12345678",
    "status": "INIT",
    "credits_reserved": 1.848
  },
  "request_id": "req_12345"
}

5. İş durumunu sorgula

GET /v1/jobs/{job_id}

Etkin veya tamamlanmış bir işin ilerlemesini ve indirme bağlantılarını getirir. Yoldaki {job_id} yerine gerçek UUID'nizi koyun.

curl --fail-with-body "https://equalang.com/v1/jobs/e861014d-72a1-4e2a-bfa3-36fa10d9978e" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

{
  "code": "OK",
  "message": "ok",
  "data": {
    "job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
    "status": "SUCCEEDED",
    "finished": true,
    "progress_percent": 100,
    "download_url": "https://example.com/download/download_url",
    "outputs": [
      {
        "kind": "translation",
        "format": "docx",
        "filename": "supply-terms.zh-cn-equalang-en.docx",
        "download_url": "https://example.com/download/download_url"
      }
    ]
  },
  "request_id": "7c7621312ab04f3da3492db98945e597"
}

6. Dosya baytlarını indir

GET /v1/files/{file_id}

API anahtarı gerektirmeyen geçici download_url adresinin aksine bu endpoint, hesabınızda saklanan herhangi bir kaynak veya çevrilmiş dosyanın ham baytlarını, dosyanın file_id değeriyle doğrudan indirmenize olanak tanır. files:read kapsamına sahip bir API anahtarı gerektirir.

curl -f "https://equalang.com/v1/files/2282396e-2b5e-43d9-853a-072c48b4d860" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -o translated_result.docx

(İkili veriyi doğrudan döndürür, JSON zarfı yok)

7. İşi iptal et

POST /v1/jobs/{job_id}/cancel

Bir işi iptal eder. İş INIT veya QUEUED durumundaysa hemen CANCELLED olur. RUNNING durumundaysa tamamen durana kadar CANCELLING durumuna geçer.

curl --fail-with-body -X POST "https://equalang.com/v1/jobs/e861014d-72a1-4e2a-bfa3-36fa10d9978e/cancel" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

{
  "code": "OK",
  "message": "ok",
  "data": {
    "job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
    "status": "CANCELLED",
    "finished": true,
    "usage": {
      "credits_reserved": 0,
      "credits_charged": 0
    }
  },
  "request_id": "502c12dff71149f588620e96b07769fb"
}

8. İşi yeniden dene

POST /v1/jobs/{job_id}/retry

Bir işi yeniden dener. İş FAILED durumunda ve error.retryable değeri true ise ya da iş daha önce CANCELLED olduysa yeniden deneyebilirsiniz. Yeniden denemek kredileri tekrar ayırır. Şuna dikkat edin: sonuç teslimi başarısız olduysa (RESULT_DELIVERY_FAILED), yeniden deneme teslimi tekrar dener ama çeviri için ikinci kez ücret almaz.

curl --fail-with-body -X POST "https://equalang.com/v1/jobs/e861014d-72a1-4e2a-bfa3-36fa10d9978e/retry" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

{
  "code": "OK",
  "message": "ok",
  "data": {
    "job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
    "status": "INIT",
    "finished": false,
    "usage": {
      "credits_reserved": 0.59,
      "credits_charged": 0
    }
  },
  "request_id": "497c3794b0a4497e890f64cc8b7d6d27"
}

9. İşleri listele

GET /v1/jobs

Çeviri ve transkripsiyon işlerinizin sayfalandırılmış listesini, en yeniden başlayarak döndürür. Sayfalar arasında gezinmek için limit ve cursor (ya da offset) değerlerini sorgu parametresi olarak gönderin.

curl --fail-with-body "https://equalang.com/v1/jobs?limit=10" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

{
  "code": "OK",
  "message": "ok",
  "data": {
    "items": [
      {
        "job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
        "status": "SUCCEEDED",
        "task": "translate"
      }
    ],
    "limit": 10,
    "offset": 0,
    "total": 39,
    "next_cursor": "MjAyNi0xMC0wOVQxOD..."
  },
  "request_id": "e79cd556afe94424a558e12ca7c2aed8"
}

10. Kredi bakiyesini kontrol et

GET /v1/credits/balance

Hesabınızdaki kullanılabilir ve dondurulmuş kredileri döndürür.

curl --fail-with-body "https://equalang.com/v1/credits/balance" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

{
  "code": "OK",
  "message": "ok",
  "data": {
    "total_credits": 125.50,
    "frozen_credits": 1.50,
    "available_credits": 124.00
  },
  "request_id": "req_bal_123"
}

Hataları yönetme

Başarısız API istekleri, nedeni ve işlemin yeniden denenebilir (retryable) olup olmadığını belirten bir hata yanıtı yüküyle birlikte standart HTTP hata durumlarını döndürür.

{
  "code": "INVALID_JOB_ID",
  "message": "Invalid job id",
  "data": null,
  "request_id": "9e97df047da640f7b60e10cfbc571711",
  "retryable": false
}

Kaynaklar

• Equalang API'nin eksiksiz belgeleri
• Equalang OpenAPI belirtimi
• Geliştiriciler için Equalang