API для разработчиков

Одно универсальное API для любого рабочего процесса с файлами

Converter App предоставляет разработчикам высокопроизводительный интерфейс для обработки файлов. Замените отдельные инструменты единым API для масштабируемой конвертации документов, обработки медиафайлов, транскрибации и OCR.

Получить доступ

Обзор API Converter App

API Converter App предоставляет разработчикам удобный универсальный интерфейс для всех задач обработки файлов. Вместо интеграции разрозненного набора отдельных инструментов ваше приложение может вызывать один высокопроизводительный сервис. Вы можете напрямую встроить весь набор конвертеров в backend-процессы, чтобы обрабатывать все — от стандартных преобразований файлов до ресурсоёмких задач с медиафайлами.

Публичный базовый URL: https://api.converter.app/. Пути в этом документе используют этот внешний корень API.

Универсальное покрытие

Получите доступ к полному набору инструментов конвертации через одну удобную интеграцию.

Два режима обработки

Выберите синхронные запросы для немедленных ответов или асинхронные задания для больших файлов и длительных операций.

Под ваши потребности

Свяжитесь с нами, и мы предложим план, адаптированный под ваши потребности, по непревзойдённой цене.

Документы Изображения Аудио Видео Текст Архивы

Ознакомьтесь с поддерживаемыми конвертациями (ключ не требуется)

Используйте публичную конечную точку pairs как самый простой тест подключения. Она не требует API ключа и возвращает полный список поддерживаемых пар конвертации, доступных на платформе.

ПОЛУЧИТЬ /public/pairs

Этот конечный пункт открыт, чтобы разработчики могли ознакомиться с универсальным каталогом конвертации перед запросом или настройкой API ключа.

curl "https://api.converter.app/public/pairs"

JavaScript

const response = await fetch('https://api.converter.app/public/pairs');
const pairs = await response.json();
console.log(pairs.supported_pairs);

Python

import requests

response = requests.get('https://api.converter.app/public/pairs')
response.raise_for_status()
pairs = response.json()
print(pairs['supported_pairs'])

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

{
  "supported_pairs": [
    { "from": "mp3", "to": "text" },
    { "from": "mp4", "to": "mp3" },
    { "from": "mov", "to": "mp4" },
    { "from": "wav", "to": "mp3" },
    { "from": "mkv", "to": "mp4" }
  ]
}

Аутентификация & контроль доступа

Разработчики проходят аутентификацию, передавая свой API ключ в HTTP заголовке X API Key. Общедоступная конечная точка /public/pairs — единственная конечная точка на этой странице, для которой не требуется ключ.

Управление	Как это работает	Влияние для разработчиков
`X-API-Key`	Отправьте ключ в заголовке HTTP запроса.	Требуется для `/pairs`, `/convert/sync`, `/convert`, `/progress/{jobid}` и `/download/{jobid}`.
Квоты на использование	У каждого ключа есть числовая квота на конвертацию. Квота уменьшается при создании задач конвертации.	Квота `-1` предоставляет неограниченное количество конвертаций. Другие значения обозначают оставшееся количество разрешённых конвертаций.
Разрешенные пары	Ключи могут быть ограничены определёнными типами конвертации, такими как `mp42mp3`, или получать доступ ко всем поддерживаемым парам `all`.	`/pairs` возвращает только пары, которые ваш ключ имеет право использовать, а запросы на конвертацию вне этого списка отклоняются.

curl "https://api.converter.app/pairs" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const response = await fetch('https://api.converter.app/pairs', {
  headers: {
    'X-API-Key': apiKey
  }
});

const pairs = await response.json();
console.log(pairs);

Python

import requests

headers = {'X-API-Key': 'YOUR_API_KEY'}
response = requests.get('https://api.converter.app/pairs', headers=headers)
response.raise_for_status()
print(response.json())

2. Синхронная конвертация

ПОСТ /convert/sync

Используйте синхронную конвертацию, если вам нужен немедленный результат в том же HTTP ответе. Запрос остаётся открытым, пока API запускает задачу конвертации и ожидает её завершения, максимум до 30 минут.

Поле формы	Тип	Описание
`target_format`	строка	Запрошенное расширение выходного файла, например `pdf`, `docx`, `mp3` или `jpg`.
`files`	file[]	Один или несколько загруженных исходных файлов. API определяет исходный формат по имени загруженного файла.

curl -X POST "https://api.converter.app/convert/sync" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "target_format=pdf" \
  -F "files=@/path/to/document.docx" \
  -o converted.pdf

JavaScript

const form = new FormData();
form.append('target_format', 'pdf');
form.append('files', fileInput.files[0]);

const response = await fetch('https://api.converter.app/convert/sync', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey
  },
  body: form
});

const convertedFile = await response.blob();

Python

import requests

headers = {'X-API-Key': 'YOUR_API_KEY'}
data = {'target_format': 'pdf'}

with open('/path/to/document.docx', 'rb') as document:
    files = {'files': document}
    response = requests.post(
        'https://api.converter.app/convert/sync',
        headers=headers,
        data=data,
        files=files
    )

response.raise_for_status()
with open('converted.pdf', 'wb') as output:
    output.write(response.content)

Ответ напрямую передает поток преобразованного файла. Если в результате конвертации создается несколько файлов, API возвращает архив .zip.

3. Асинхронная конвертация

ПОСТ /convert

Используйте асинхронную конвертацию для больших файлов, пакетной обработки, длительных задач с аудио или видео, а также для производственных приложений, которым не следует удерживать запросы на загрузку открытыми, пока выполняется работа.

Поле формы	Тип	Описание
`target_format`	строка	Желаемый формат результата. Исходный и целевой формируют пару конвертации, например `mp42mp3`.
`files`	file[]	Один или несколько файлов для конвертации.

cURL

curl -X POST "https://api.converter.app/convert" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "target_format=mp3" \
  -F "files=@/path/to/video.mp4"

JavaScript

const form = new FormData();
form.append('target_format', 'mp3');
form.append('files', fileInput.files[0]);

const response = await fetch('https://api.converter.app/convert', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey
  },
  body: form
});

const job = await response.json();
console.log(job.jobid, job.remaining_quota);

Python

import requests

headers = {'X-API-Key': 'YOUR_API_KEY'}
data = {'target_format': 'mp3'}

with open('/path/to/video.mp4', 'rb') as video:
    files = {'files': video}
    response = requests.post(
        'https://api.converter.app/convert',
        headers=headers,
        data=data,
        files=files
    )

response.raise_for_status()
job = response.json()
print(job['jobid'], job['remaining_quota'])

Успешный ответ

{
  "status": "success",
  "jobid": "b3f6b2e8f5c34c4ab01c93c4d1b2f9e8",
  "pair": "mp42mp3",
  "remaining_quota": 42
}

4. Отслеживание статуса

ПОЛУЧИТЬ /progress/{jobid}

Опросите этот конечный адрес после создания асинхронной задачи. Он возвращает статус задачи, числовое значение прогресса от 0.0 до 1.0 и сведения об ошибке, если конвертация не удалась.

Заголовок	Описание
`X-API-Key`	Ваш ключ API разработчика.

curl "https://api.converter.app/progress/b3f6b2e8f5c34c4ab01c93c4d1b2f9e8" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const response = await fetch('https://api.converter.app/progress/b3f6b2e8f5c34c4ab01c93c4d1b2f9e8', {
  headers: {
    'X-API-Key': apiKey
  }
});

const progress = await response.json();
console.log(progress.status, progress.progress);

Python

import requests

headers = {'X-API-Key': 'YOUR_API_KEY'}
response = requests.get(
    'https://api.converter.app/progress/b3f6b2e8f5c34c4ab01c93c4d1b2f9e8',
    headers=headers
)
response.raise_for_status()
progress = response.json()
print(progress['status'], progress['progress'])

{
  "jobid": "b3f6b2e8f5c34c4ab01c93c4d1b2f9e8",
  "progress": 1.0,
  "status": "completed",
  "error": null
}

Возможные статусы: processing, completed и failed. Прогресс — это число от 0.0 до 1.0.

5. Получение файла

ПОЛУЧИТЬ /download/{jobid}

После того как асинхронная задача достигнет состояния completed, получите преобразованный результат, используя тот же API ключ, который был использован для создания задачи.

Тип результата	Поведение
Один выходной файл	API передает преобразованный файл напрямую.
`resultfile` манифест	Если задача предоставляет манифест результатов, API возвращает файл, указанный в этом манифесте.
Несколько выходных файлов	API упаковывает сгенерированные файлы в архив `.zip` на лету.

curl -L "https://api.converter.app/download/b3f6b2e8f5c34c4ab01c93c4d1b2f9e8" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o converted-output.zip

JavaScript

const response = await fetch('https://api.converter.app/download/b3f6b2e8f5c34c4ab01c93c4d1b2f9e8', {
  headers: {
    'X-API-Key': apiKey
  }
});

const file = await response.blob();

Python

import requests

headers = {'X-API-Key': 'YOUR_API_KEY'}
response = requests.get(
    'https://api.converter.app/download/b3f6b2e8f5c34c4ab01c93c4d1b2f9e8',
    headers=headers
)
response.raise_for_status()

with open('converted-output.zip', 'wb') as output:
    output.write(response.content)

Краткое описание рабочего процесса разработчика

API поддерживает два шаблона интеграции, поэтому разработчики могут выбрать подходящее поведение для каждого сценария использования.

Поток	Шаблон запроса	Лучше всего для
Быстрый поток синхронизации	`POST /convert/sync` возвращает конвертированный файл в том же ответе.	Небольшие файлы, скрипты командной строки, прототипы и простые серверные автоматизации.
Надёжный асинхронный процесс	`POST /convert`, затем опрашивайте `GET /progress/{jobid}`, затем вызовите `GET /download/{jobid}`.	Большие видео- или аудиофайлы, пакетная конвертация, серверная часть веб-приложений и производственные системы с поддержкой повторных попыток.

Пример асинхронного потока

# 1. Start the job
curl -X POST "https://api.converter.app/convert" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "target_format=mp3" \
  -F "files=@/path/to/video.mp4"

# 2. Poll until completed
curl "https://api.converter.app/progress/JOBID" \
  -H "X-API-Key: YOUR_API_KEY"

# 3. Download the finished output
curl -L "https://api.converter.app/download/JOBID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o result.mp3

JavaScript

const form = new FormData();
form.append('target_format', 'mp3');
form.append('files', fileInput.files[0]);

const createResponse = await fetch('https://api.converter.app/convert', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey
  },
  body: form
});
const job = await createResponse.json();

const progressResponse = await fetch(`https://api.converter.app/progress/${job.jobid}`, {
  headers: {
    'X-API-Key': apiKey
  }
});
const progress = await progressResponse.json();

if (progress.status === 'completed') {
  const downloadResponse = await fetch(`https://api.converter.app/download/${job.jobid}`, {
    headers: {
      'X-API-Key': apiKey
    }
  });
  const result = await downloadResponse.blob();
}

Python

import requests

headers = {'X-API-Key': 'YOUR_API_KEY'}
data = {'target_format': 'mp3'}

with open('/path/to/video.mp4', 'rb') as video:
    files = {'files': video}
    create_response = requests.post(
        'https://api.converter.app/convert',
        headers=headers,
        data=data,
        files=files
    )

create_response.raise_for_status()
job = create_response.json()

progress_response = requests.get(
    f"https://api.converter.app/progress/{job['jobid']}",
    headers=headers
)
progress_response.raise_for_status()
progress = progress_response.json()

if progress['status'] == 'completed':
    download_response = requests.get(
        f"https://api.converter.app/download/{job['jobid']}",
        headers=headers
    )
    download_response.raise_for_status()
    with open('result.mp3', 'wb') as output:
        output.write(download_response.content)

Ответы об ошибках

Ошибки возвращаются в формате JSON с полем detail и использованием стандартных HTTP кодов состояния.

Статус	Распространённая причина
`400`	Отсутствуют файлы, отсутствует `target_format`, неподдерживаемый формат ID задания или некорректные данные запроса.
`401`	Отсутствует или недействителен `X API Key`.
`403`	API ключу не разрешено использовать запрошенную пару конвертации.
`404`	Запрошенная задача или сгенерированный файл результата недоступен.
`409`	Преобразование все еще выполняется, когда запрашивается загрузка.
`429`	У API ключа закончилась квота.
`500`	Преобразование не удалось подготовить или завершить из-за ошибки обработки на стороне сервера.

{
  "detail": "This API key is not authorized for mp42mp3 conversions."
}

Одно универсальное API для любого рабочего процесса с файлами

Обзор API Converter App

Ознакомьтесь с поддерживаемыми конвертациями (ключ не требуется)

JavaScript

Python

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

Аутентификация & контроль доступа

JavaScript

Python

2. Синхронная конвертация

JavaScript

Python

3. Асинхронная конвертация

cURL

JavaScript

Python

Успешный ответ

4. Отслеживание статуса

JavaScript

Python

5. Получение файла

JavaScript

Python

Краткое описание рабочего процесса разработчика

Пример асинхронного потока

JavaScript

Python

Ответы об ошибках

Конфиденциальность и условия

Contact