TransConvert API

От нуля до первого конвертированного файла за три шага.

Каждый запрос требует API-ключ, который передаётся как Bearer-токен в заголовке Authorization.

Доступно на тарифах Basic, Lite, Pro и Team. Создать ключ в личном кабинете →

Проверьте ключ

Быстрый способ убедиться, что ключ работает, ещё до написания реального кода интеграции — сам по себе этот запрос ничего не конвертирует (файл не прикреплён), но ответ 400 no_file вместо 401 подтверждает, что ключ действителен.

Один эндпоинт обрабатывает все виды конвертации. Отправьте POST-запрос multipart/form-data с файлом и указанными ниже полями.

Параметры

Частые варианты конвертации

Краткий справочник по популярным парам форматов — один и тот же эндпоинт обрабатывает их все, просто с разным сочетанием category/target.

Ответ

При успехе (200): необработанные байты конвертированного файла с соответствующими заголовками Content-Type и Content-Disposition. При ошибке: JSON-тело вида {"error": {"code": "...", "message": "..."}} с соответствующим HTTP-статусом — см. раздел «Ошибки» ниже.

Уменьшите размер файла без изменения формата — на входе и выходе один и тот же формат. Отдельная от конвертации пара категорий, image-compress и document-compress, у каждой свои параметры ниже.

image-compress

На входе и выходе один и тот же формат (JPG/PNG/WEBP/GIF) — target_percent задаёт, насколько маленьким должен получиться результат относительно оригинала, а не фиксированный уровень качества.

curl -X POST \
  https://transconvert.com/api/v1/convert.php \
  -H "Authorization: Bearer tc_live_your_key_here" \
  -F "category=image-compress" \
  -F "target_percent=50" \
  -F "file=@photo.jpg" \
  -o compressed.jpg

document-compress

PDF на входе, PDF на выходе — через собственное пересжатие Ghostscript. Результат никогда не будет больше загруженного файла (если пересжатие не помогло, возвращается оригинал).

curl -X POST \
  https://transconvert.com/api/v1/convert.php \
  -H "Authorization: Bearer tc_live_your_key_here" \
  -F "category=document-compress" \
  -F "level=high" \
  -F "file=@report.pdf" \
  -o compressed.pdf

Конвертация видео и аудио может занимать несколько минут — слишком долго, чтобы держать открытым один синхронный запрос, поэтому вместо эндпоинта выше здесь используется схема «отправить, затем опрашивать». Отправьте файл, сразу получите job_id в ответ, а затем опрашивайте его статус, пока задача не завершится.

Отправка задачи

Тот же формат multipart POST-запроса, что и у основного эндпоинта, но по другому адресу.

curl -X POST \
  https://transconvert.com/api/v1/convert-async.php \
  -H "Authorization: Bearer tc_live_your_key_here" \
  -F "category=video" \
  -F "target=MP4" \
  -F "file=@clip.mov"

Ответ (202 Accepted)

{ "job_id": "job_242e1555d78d166807aa56502f15d118", "status": "queued" }

Опрос статуса

Опрашивайте этот адрес каждые несколько секунд, передавая полученный job_id. «status» принимает одно из значений: queued, processing, completed или failed.

{
  "job_id": "job_242e1555d78d166807aa56502f15d118",
  "status": "completed",
  "category": "video",
  "target_format": "MP4",
  "created_at": "2026-08-26 19:17:47",
  "download_url": "/api/v1/job-status.php?job_id=job_...&download=1",
  "filename": "clip.mp4"
}

Вебхуки (необязательно)

Если вы указали webhook_url при отправке, мы один раз отправим туда тот же JSON, когда задание завершится — при успехе или ошибке — с несколькими повторными попытками, если ваш эндпоинт не отвечает. job-status.php по-прежнему работает как резервный вариант.

POST your webhook_url
{
  "job_id": "job_242e1555d78d166807aa56502f15d118",
  "status": "completed",
  "category": "video",
  "target_format": "MP4",
  "created_at": "2026-08-26 19:17:47",
  "download_url": "https://transconvert.com/api/v1/job-status.php?job_id=job_...&download=1",
  "filename": "clip.mp4"
}

Скачивание результата

Когда status становится «completed», в ответе появляется download_url — тот же адрес статуса с добавленным &download=1. Запрос по нему передаёт необработанные байты конвертированного файла с теми же заголовками, что и у остальных эндпоинтов на этой странице. Результат удаляется сразу после скачивания либо автоматически по истечении короткого срока хранения, если его так и не скачали.

scheduleРезультаты задач удаляются сразу после скачивания либо автоматически по истечении короткого срока хранения, если их так и не скачали — скачивайте их не откладывая.

Один и тот же запрос на четырёх языках — выберите тот, что подходит вашему стеку. Каждый пример конвертирует локальный файл photo.jpg в PNG и сохраняет результат.

curl -X POST \
  https://transconvert.com/api/v1/convert.php \
  -H "Authorization: Bearer tc_live_your_key_here" \
  -F "category=image" \
  -F "target=PNG" \
  -F "file=@photo.jpg" \
  -o converted.png

<?php
$ch = curl_init('https://transconvert.com/api/v1/convert.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer tc_live_your_key_here'],
    CURLOPT_POSTFIELDS => [
        'category' => 'image',
        'target' => 'PNG',
        'file' => new CURLFile('photo.jpg'),
    ],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status === 200) {
    file_put_contents('converted.png', $response);
} else {
    $error = json_decode($response, true);
    echo $error['error']['message'];
}

const form = new FormData();
form.append('category', 'image');
form.append('target', 'PNG');
form.append('file', new Blob([fs.readFileSync('photo.jpg')]), 'photo.jpg');

const res = await fetch('https://transconvert.com/api/v1/convert.php', {
  method: 'POST',
  headers: { Authorization: 'Bearer tc_live_your_key_here' },
  body: form,
});

if (res.ok) {
  fs.writeFileSync('converted.png', Buffer.from(await res.arrayBuffer()));
} else {
  const { error } = await res.json();
  console.error(error.message);
}

import requests

with open('photo.jpg', 'rb') as f:
    response = requests.post(
        'https://transconvert.com/api/v1/convert.php',
        headers={'Authorization': 'Bearer tc_live_your_key_here'},
        data={'category': 'image', 'target': 'PNG'},
        files={'file': f},
    )

if response.status_code == 200:
    with open('converted.png', 'wb') as out:
        out.write(response.content)
else:
    print(response.json()['error']['message'])

# gem install multipart-post
require 'net/http'
require 'net/http/post/multipart'

url = URI('https://transconvert.com/api/v1/convert.php')

File.open('photo.jpg') do |file|
  req = Net::HTTP::Post::Multipart.new url,
    'category' => 'image',
    'target' => 'PNG',
    'file' => UploadIO.new(file, 'image/jpeg', 'photo.jpg')
  req['Authorization'] = 'Bearer tc_live_your_key_here'

  res = Net::HTTP.start(url.host, url.port, use_ssl: true) do |http|
    http.request(req)
  end

  if res.code == '200'
    File.write('converted.png', res.body)
  else
    puts JSON.parse(res.body)['error']['message']
  end
end

// Gradle: implementation("com.squareup.okhttp3:okhttp:4.+")
OkHttpClient client = new OkHttpClient();

RequestBody body = new MultipartBody.Builder()
    .setType(MultipartBody.FORM)
    .addFormDataPart("category", "image")
    .addFormDataPart("target", "PNG")
    .addFormDataPart("file", "photo.jpg",
        RequestBody.create(new File("photo.jpg"), MediaType.parse("image/jpeg")))
    .build();

Request request = new Request.Builder()
    .url("https://transconvert.com/api/v1/convert.php")
    .header("Authorization", "Bearer tc_live_your_key_here")
    .post(body)
    .build();

try (Response response = client.newCall(request).execute()) {
    if (response.isSuccessful()) {
        Files.write(Paths.get("converted.png"), response.body().bytes());
    } else {
        System.err.println(response.body().string());
    }
}

Каждая ошибка возвращает JSON с полем «code», по которому можно ветвить логику в коде, и человекочитаемым «message». Некоторые ошибки содержат дополнительные поля (например, quota_exceeded включает «limit» и «used»).

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly API allowance of 5000 conversion-minutes reached.",
    "limit": 5000,
    "used": 5000
  }
}

Обработка ошибок и повторные попытки

Ветвите логику по полю JSON «code», а не по тексту «message» — формулировки могут меняться со временем, а код — нет. concurrency_limit имеет смысл повторить через несколько секунд (лимит снимается, как только завершится одна из ваших текущих конвертаций); quota_exceeded сам по себе не исчезнет до следующего месяца, поэтому не повторяйте запрос в цикле. conversion_failed — единственный код, где важен именно HTTP-статус: 503 — временная проблема на стороне сервера, стоит повторить один раз; а 400/415/422/500 означают, что именно эта комбинация файла и формата назначения не сработает, сколько бы раз вы ни отправляли запрос. Проверка размера файла на стороне клиента перед загрузкой позволяет не тратить запрос на заведомый file_too_large.

API использует те же лимиты, что и ваш тариф на сайте — отдельно ничего настраивать не нужно.

Как только начинает действовать лимит в минуту, каждый ответ содержит заголовки X-RateLimit-Limit и X-RateLimit-Remaining; ответ 429 также содержит Retry-After (в секундах) — используйте их, чтобы снизить частоту запросов заранее, а не реагировать только после 429.

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

infoКонвертация и сжатие видео и аудио пока доступны только на сайте: синхронный HTTP-запрос плохо подходит для задачи, которая может занимать несколько минут.