Примеры API

Версия

API

Маршрут

POST PUT POST

/api/v2/api/translate/uploads
R2 target
/api/v2/api/translate

Параметры

Параметр	Обязательно	Тип	Описание
`image`	Да	file[]	Один или несколько файлов изображений либо один ZIP-архив
`source_language`	Нет	string	Необязательно; обязательно для модели manga (например, ja)
`target_language`	Да	string	Код целевого языка (например, en)
`model`	Нет	string	Модель распознавания; не указывайте, чтобы использовать значение API по умолчанию
`font`	Нет	string	Стиль шрифта; не указывайте, чтобы использовать значение API по умолчанию

Параметр	Обязательно	Тип	Описание
`Idempotency-Key`	Да	HTTP header	Заголовок запроса подготовки: стабильный ключ для безопасного повтора того же списка файлов в течение 8 часов
`platform`	Нет	string \| null	Запросы подготовки и завершения: необязательная метка платформы, указанная клиентом и используемая только для аудита вызовов API
`files[]`	Да	array<object>	Запрос подготовки: метаданные файла с filename, content_type, size и content_sha256
`upload_id`	Да	string	Финальный запрос: непрозрачный идентификатор пакета загрузки, полученный при подготовке
`files[].index files[].upload_intent`	Да	integer string	Финальный запрос: index и непрозрачный upload_intent для каждого файла, полученные при подготовке; отправляйте только после завершения каждой загрузки в R2
`source_language`	Нет	string	Необязательно; обязательно для модели manga (например, ja)
`target_language`	Да	string	Код целевого языка (например, en)
`model`	Нет	string	Модель распознавания; не указывайте, чтобы использовать значение API по умолчанию
`font`	Нет	string	Стиль шрифта; не указывайте, чтобы использовать значение API по умолчанию

Параметр	Обязательно	Тип	Описание
`batch_id`	Да	string	Идентификатор пакета для запроса статуса задачи

Параметр	Обязательно	Тип	Описание
Нет параметров

Параметры ответа

Поле	Тип	Описание
`task_id`	string	Идентификатор задачи
`batch_id`	string	Идентификатор пакета для запроса статуса задачи

Поле	Тип	Описание
`status`	integer	Код состояния приложения; 200 при успешном ответе
`cost_ms`	integer	Время обработки этого API-запроса в миллисекундах
`request_id`	string	Идентификатор запроса для отслеживания этого вызова API
`data`	object	Идентификаторы задачи перевода, возвращаемые после принятия запроса
`message`	string	Всегда success при успешном ответе API; это не означает, что задача перевода завершена
`data.task_id`	string	Идентификатор задачи
`data.batch_id`	string	Идентификатор пакета для запроса статуса задачи

Поле	Тип	Описание
`status_code`	integer	Всегда 200 для успешного ответа Task Status
`request_id`	string	Идентификатор запроса для отслеживания этого вызова API
`auth_type`	string	Всегда account для запроса Task Status, аутентифицированного с помощью PAT
`task_reference`	string	batch_id из пути запроса, возвращённый без изменений
`data`	object	Контейнер результатов по изображениям и общего статуса задачи
`data.items`	array<object>	Массив результатов задачи для каждого изображения
`data.items[].image_id`	string	Стабильный идентификатор результата изображения
`data.items[].index`	integer	Позиция изображения в пакете, начиная с нуля
`data.items[].filename`	string	Имя файла исходного изображения
`data.items[].status`	string	Статус результата изображения (pending \| processing \| completed \| failed \| canceled)
`data.items[].original_url`	string	URL исходного изображения; доступен для текущих задач, созданных через API.
`data.items[].translated_url`	string	URL переведённого изображения; пустая строка до появления результата, в том числе для ожидающих, обрабатываемых или завершившихся ошибкой изображений.
`data.items[].is_translated`	boolean	true, только если доступен URL готового переведённого изображения
`data.items[].output_file_path`	string	Совместимый псевдоним translated_url; пустая строка, если переведённое изображение недоступно.
`data.items[].message`	string \| null	Необязательное информационное сообщение
`data.items[].error`	string \| null	Сведения об ошибке при сбое задачи изображения; иначе null
`data.items[].inpaint_image_url`	string \| null	URL изображения с удалённым текстом или null, если выбранная модель либо путь выполнения его не создаёт.
`data.items[].block_json`	array<object>	Структурированные текстовые блоки, сохранённые в V1; может быть пустым массивом, если модель или путь не возвращает метаданные блоков.
`data.task_status`	string	Общий статус задачи (pending \| processing \| completed \| failed \| canceled)

Поле	Тип	Описание
`status`	integer	Код состояния приложения; 200 при успешном ответе
`cost_ms`	integer	Время выполнения задачи в миллисекундах; 0 при отсутствии корректных временных меток
`request_id`	string	Идентификатор запроса для отслеживания этого вызова API
`data`	array<object>	Массив компактных результатов для каждого изображения
`message`	string	Всегда success при успешном ответе API; это не означает, что задача перевода завершена
`data[].image_id`	string	Стабильный идентификатор результата изображения
`data[].filename`	string	Имя файла исходного изображения
`data[].status`	string	Статус результата изображения (pending \| processing \| completed \| failed \| canceled)
`data[].original_url`	string	URL исходного изображения; доступен для текущих задач, созданных через API.
`data[].translated_url`	string	URL переведённого изображения; пустая строка до появления результата, в том числе для ожидающих, обрабатываемых или завершившихся ошибкой изображений.
`data[].erased_url`	string	URL изображения с удалённым текстом; может быть пустой строкой. Модели или пути, возвращающие только готовое изображение, например Manga с путём готового изображения Auto, его не создают.
`data[].blocks`	array<object>	Структурированные блоки переведённого текста; может быть пустым массивом, если модель или путь не возвращает метаданные блоков, например Manga с путём готового изображения Auto.
`data[].blocks[].angle`	number	Угол поворота текстового блока
`data[].blocks[].color`	string	Шестнадцатеричный цвет переведённого текста
`data[].blocks[].handwritten`	boolean	Был ли исходный текст распознан как рукописный
`data[].blocks[].location`	object	Границы текстового блока по четырём углам
`data[].blocks[].location.left_bottom`	array<number>	Пара координат указанного угла
`data[].blocks[].location.right_bottom`	array<number>	Пара координат указанного угла
`data[].blocks[].location.left_top`	array<number>	Пара координат указанного угла
`data[].blocks[].location.right_top`	array<number>	Пара координат указанного угла
`data[].blocks[].text`	string	Переведённый текст, отображаемый в блоке
`data[].blocks[].direction`	string	Направление письма переведённого текста

Поле	Тип	Описание
`subscription_credits`	integer	Баланс кредитов указанной категории
`subscription_credits_expires_at`	string \| null	Срок действия кредитов подписки в формате ISO 8601 или null
`one_time_credits`	integer	Баланс кредитов указанной категории
`one_time_credits_expires_at`	string \| null	Срок действия разовых кредитов в формате ISO 8601 или null
`free_credits`	integer	Баланс кредитов указанной категории
`total_credits`	integer	Сумма всех доступных балансов кредитов
`is_temporary`	boolean	Принадлежит ли баланс временному аккаунту

Поле	Тип	Описание
`status`	integer	Код состояния приложения; 200 при успешном ответе
`cost_ms`	integer	Время обработки этого API-запроса в миллисекундах
`request_id`	string	Идентификатор запроса для отслеживания этого вызова API
`data`	object	Контейнер текущих балансов кредитов
`message`	string	Всегда success при успешном ответе API; это не означает, что задача перевода завершена
`data.total_credits`	integer	Сумма всех доступных балансов кредитов
`data.is_temporary`	boolean	Принадлежит ли баланс временному аккаунту
`data.detail`	object	Распределение доступных кредитов по категориям
`data.detail.subscription`	object	Баланс и срок действия указанной категории
`data.detail.subscription.credits`	integer	Баланс кредитов указанной категории
`data.detail.subscription.expires_at`	string \| null	Срок действия кредита в формате ISO 8601 или null
`data.detail.one_time`	object	Баланс и срок действия указанной категории
`data.detail.one_time.credits`	integer	Баланс кредитов указанной категории
`data.detail.one_time.expires_at`	string \| null	Срок действия кредита в формате ISO 8601 или null
`data.detail.free`	object	Баланс и срок действия указанной категории
`data.detail.free.credits`	integer	Баланс кредитов указанной категории
`data.detail.free.expires_at`	null	Всегда null, так как этот агрегирующий endpoint не предоставляет единый срок действия бесплатных кредитов

Пример ответа (JSON)

{
  "task_id": "00000000-0000-4000-8000-000000000001",
  "batch_id": "00000000-0000-4000-8000-000000000001"
}

Пример ответа (JSON)

{
  "status": 200,
  "cost_ms": 125,
  "request_id": "4b7370383cacccc7",
  "data": {
    "task_id": "00000000-0000-4000-8000-000000000001",
    "batch_id": "00000000-0000-4000-8000-000000000001"
  },
  "message": "success"
}

Пример ответа (JSON)

{
  "status_code": 200,
  "request_id": "4b7370383cacccc7",
  "auth_type": "account",
  "task_reference": "00000000-0000-4000-8000-000000000001",
  "data": {
    "items": [
      {
        "image_id": "00000000-0000-4000-8000-000000000001_0",
        "index": 0,
        "filename": "007.jpg",
        "status": "completed",
        "original_url": "https://storage.example.com/manga-demo/input/00000000-0000-4000-8000-000000000001/007.jpg",
        "translated_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
        "is_translated": true,
        "output_file_path": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
        "message": "ok",
        "error": null,
        "inpaint_image_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007-erased.jpg",
        "block_json": []
      }
    ],
    "task_status": "completed"
  }
}

Пример ответа (JSON)

{
  "status": 200,
  "cost_ms": 5300,
  "request_id": "4b7370383cacccc7",
  "data": [
    {
      "image_id": "00000000-0000-4000-8000-000000000001_0",
      "filename": "007.jpg",
      "status": "completed",
      "original_url": "https://storage.example.com/manga-demo/input/00000000-0000-4000-8000-000000000001/007.jpg",
      "translated_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
      "erased_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007-erased.jpg",
      "blocks": [
        {
          "angle": 0,
          "color": "#484848",
          "handwritten": false,
          "location": {
            "left_bottom": [1685, 293],
            "right_bottom": [1786, 293],
            "left_top": [1685, 264],
            "right_top": [1786, 264]
          },
          "text": "OOOUGH!",
          "direction": "horizontal"
        }
      ]
    }
  ],
  "message": "success"
}

Пример ответа (JSON)

{
  "subscription_credits": 0,
  "subscription_credits_expires_at": null,
  "one_time_credits": 0,
  "one_time_credits_expires_at": null,
  "free_credits": 10,
  "total_credits": 10,
  "is_temporary": true
}

Пример ответа (JSON)

{
  "status": 200,
  "cost_ms": 4,
  "request_id": "4b7370383cacccc7",
  "data": {
    "total_credits": 10,
    "is_temporary": true,
    "detail": {
      "subscription": {
        "credits": 0,
        "expires_at": null
      },
      "one_time": {
        "credits": 0,
        "expires_at": null
      },
      "free": {
        "credits": 10,
        "expires_at": null
      }
    }
  },
  "message": "success"
}

Параметры ответа с ошибкой

При ошибке V2 статус HTTP сохраняется и возвращается та же структура ответа из пяти полей.

Поле	Тип	Описание
`status`	integer	Фактический код HTTP-статуса ошибки
`cost_ms`	integer	Время обработки этого API-запроса в миллисекундах
`request_id`	string	Идентификатор запроса для отслеживания этого вызова API
`data`	object	Контейнер данных об ошибке, содержащий только стабильный машиночитаемый код
`message`	string	Публичное сообщение об ошибке; внутренние диагностические сведения не раскрываются
`data.code`	string	Стабильный машиночитаемый код ошибки

Пример ответа с ошибкой (JSON)

{
  "status": 400,
  "cost_ms": 1,
  "request_id": "4b7370383cacccc7",
  "data": {
    "code": "PZ_API_ACCESS_BAD_REQUEST"
  },
  "message": "Invalid target language"
}

Пример входных данных

API-ключ

Исходный язык

Целевой язык

Модель

Шрифт

Примеры API

Маршрут

Параметры

Параметры ответа

Пример ответа (JSON)

Пример ответа (JSON)

Пример ответа (JSON)

Пример ответа (JSON)

Пример ответа (JSON)

Пример ответа (JSON)

Параметры ответа с ошибкой

Пример ответа с ошибкой (JSON)

Пример входных данных

Пример Python3

Примеры cURL

Пример Python3

cURL

Пример Python3

cURL

Маршрут

Параметры

Параметры ответа

Пример ответа (JSON)

Пример ответа (JSON)

Пример ответа (JSON)

Пример ответа (JSON)

Пример ответа (JSON)

Пример ответа (JSON)

Параметры ответа с ошибкой

Пример ответа с ошибкой (JSON)

Пример входных данных

Пример Python3

Примеры cURL

Пример Python3

cURL

Пример Python3

cURL

Настройки файлов cookie