Справочник Equalang API и быстрый старт

При интеграции Equalang в свой бэкенд управления или рабочий процесс вы можете мгновенно переводить текст либо обрабатывать целые файлы — документы, аудио и видео — с сохранением исходной вёрстки там, где это поддерживается.

Это руководство даёт быстрый старт по рабочему процессу перевода файлов на cURL и Python, а затем — полный справочник по всем 10 публичным эндпоинтам API.

Аутентификация и стандартный ответ

API Equalang доступно по адресу https://equalang.com/v1. Аутентифицируйте каждый запрос, передавая свой API-ключ в HTTP-заголовке Authorization:

Authorization: Bearer el_your_api_key_here

У вашего API-ключа должны быть нужные области действия (scope): например, translations:document для задач, translations:text для текста, files:read для прямого скачивания файлов.

Стандартная обёртка ответа: все успешные ответы JSON используют стандартную структуру верхнего уровня. Ради краткости структурные примеры ниже опускают некоторые несущественные поля, но остаются полностью корректными объектами JSON. Приведённые идентификаторы, URL и числа баланса чисто иллюстративны: используйте фактические значения из своих ответов.

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

Быстрый старт: асинхронный перевод файлов

Обработка целого документа требует асинхронного процесса: загрузите файл, чтобы запустить задачу, опрашивайте её статус и скачайте результат. Можно взять свой файл либо скачать наш пример supply-confirmation.zh-CN.docx для пробы.

Способ 1: с помощью cURL

Сначала экспортируйте свой API-ключ (создать его можно на https://equalang.com/api-keys):

export EQUALANG_API_KEY="el_your_api_key_here"

1. Загрузите файл и запустите задачу

Отправьте файл напрямую. API резервирует необходимые кредиты и возвращает job_id. Укажите уникальный Idempotency-Key (например, UUID), чтобы при тайм-ауте не возникло дублирующих задач. Используйте тот же ключ, если нужно повторить ту же отправку, и создавайте новый для новых задач. (Убедитесь, что локально есть файл report.docx, либо измените имя в коде.)

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"

Извлеките job_id из объекта data ответа, чтобы использовать его на следующем шаге. Не копируйте исторические идентификаторы из примеров.

2. Опрашивайте статус задачи

Используйте свой job_id, чтобы следить за прогрессом. Между запросами выдерживайте длительность, рекомендованную заголовком Retry-After. Прекратите опрос, когда finished станет true.

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

3. Скачайте результат

Когда статус станет SUCCEEDED, ответ будет содержать временный download_url. Этот адрес использует временную авторизацию по подписи, поэтому при скачивании с него не нужно (и не следует) отправлять свой API-токен Bearer. Используйте флаг вроде -f, чтобы при HTTP-ошибках завершаться без лишнего вывода и не сохранить страницу с ошибкой вместо файла.

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

Способ 2: с помощью Python (requests)

Примечание: нужна библиотека requests (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)

Для продвинутых сценариев (например, сначала проверить расчёт стоимости или восстановить потерянные состояния опроса) можно скачать наш расширенный скрипт translate_file.py.

---

Справочник эндпоинтов

Ниже — подробности и примеры структуры полезной нагрузки для всех 10 публичных эндпоинтов.

Точные коды поддерживаемых языков (например, zh-CN, en) смотрите в перечислениях DocumentLanguage и TextLanguage в схеме OpenAPI либо в руководстве для разработчиков. Код auto допустим только для source_language.

1. Перевод текста

POST /v1/text/translate

Синхронный перевод текстовых строк. Оплата начисляется только за успешно переведённые тексты. detected_source_language равен null, если конкретный язык не был определён автоматически.

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. Загрузка файла для расчёта стоимости

POST /v1/files

Если до перевода нужно показать максимально возможную стоимость, загрузите файл здесь. В ответе придут file_id и quote — сколько кредитов потребуется.

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. Создание задачи перевода документа

POST /v1/jobs/translate

Создаёт асинхронную задачу перевода. Принимает file (multipart), file_url или file_id.

# 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. Создание задачи транскрибации

POST /v1/jobs/transcribe

Извлекает и возвращает устную речь из аудио- или видеофайла в виде субтитров с таймкодами, без перевода.

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. Запрос статуса задачи

GET /v1/jobs/{job_id}

Возвращает прогресс и ссылки для скачивания активной или завершённой задачи. Подставьте вместо {job_id} в пути свой фактический UUID.

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. Скачивание байтов файла

GET /v1/files/{file_id}

В отличие от временного download_url (для него ключ не нужен), этот эндпоинт позволяет скачать «сырые» байты любого исходного или переведённого файла, хранящегося в вашем аккаунте, напрямую по его file_id. Нужен API-ключ с областью files:read.

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

(Возвращает двоичные данные напрямую, без обёртки JSON)

7. Отмена задачи

POST /v1/jobs/{job_id}/cancel

Отменяет задачу. Если задача в состоянии INIT или QUEUED, она сразу становится CANCELLED. Если она RUNNING, она переходит в состояние CANCELLING до полной остановки.

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. Повтор задачи

POST /v1/jobs/{job_id}/retry

Повторяет задачу. Повтор возможен, если задача FAILED и её error.retryable равен true, либо если она была CANCELLED. При повторе кредиты резервируются снова. Учтите: если не удалась доставка результата (RESULT_DELIVERY_FAILED), повтор снова попытается доставить его, но за перевод второй раз с вас не спишут.

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. Список задач

GET /v1/jobs

Возвращает постраничный список ваших задач перевода и транскрибации, начиная с самых новых. Для постраничного вывода передайте limit и cursor (или offset) как параметры запроса.

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. Проверка баланса кредитов

GET /v1/credits/balance

Возвращает доступные и замороженные кредиты вашего аккаунта.

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

Обработка ошибок

Неудачные запросы к API возвращают стандартные статусы ошибок HTTP вместе с телом ответа, в котором указаны причина и то, можно ли повторить операцию (retryable).

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

Источники

• Полная документация Equalang API
• Спецификация OpenAPI Equalang
• Equalang для разработчиков