Image Conversion API
Convert images between JPG, PNG, GIF, WEBP, BMP, AVIF, PDF, ICO, PSD, TIFF, EPS, and HEIC (source only) with one POST request — the exact engine behind TransConvert's website converter.
curl -X POST \ .../api/v1/convert.php \ -H "Authorization: Bearer ..." \ -F "category=image" \ -F "target=PNG" \ -F "file=@photo.jpg" \ -o output.png
https://transconvert.com/api/v1/convert.php
Parâmetros
| Field | Description |
|---|---|
Authorization | Required. "Bearer tc_live_...". |
category | Set to "image". |
target | Required. Output format code, e.g. "PNG", "PDF", "ICO". |
file | Required. The image (or PDF, when converting a PDF page to an image). |
pdf_mode | "pages" (default) or "extract" — only relevant when the source is a PDF. |
pdf_pages | "all" (default) or "first" — only relevant when the source is a PDF. |
pdf_quality | "normal" (default, 150 DPI) or "high" (300 DPI) — only relevant when the source is a PDF. |
Exemplos
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 output.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('output.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('output.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('output.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, 'application/octet-stream', '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('output.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("application/octet-stream"))) .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("output.png"), response.body().bytes()); } else { System.err.println(response.body().string()); } }
Resposta
Em caso de sucesso (200): os bytes brutos do arquivo convertido, com os cabeçalhos Content-Type e Content-Disposition definidos para ele. Em caso de falha: um corpo JSON no formato {"error": {"code": "...", "message": "..."}} com um código de status HTTP correspondente — veja Erros abaixo.
| Header | Value |
|---|---|
Content-Type | O tipo MIME real do arquivo convertido (ex.: image/png, application/pdf). |
Content-Disposition | attachment; filename="..." — um nome de arquivo sugerido, como em qualquer download de arquivo. |
Content-Length | Tamanho do corpo da resposta em bytes. |
Todo erro segue o mesmo formato JSON, por exemplo quando uma cota é excedida:
{
"error": {
"code": "quota_exceeded",
"message": "Monthly API allowance of 5000 conversion-minutes reached.",
"limit": 5000,
"used": 5000
}
}
Erros
Toda falha retorna um envelope de erro JSON com um "code" no qual seu código pode se basear, além de uma "message" legível por humanos. Alguns erros incluem campos extras (quota_exceeded inclui "limit" e "used", por exemplo).
| Status & code | When it happens |
|---|---|
401 missing_key | Nenhum cabeçalho Authorization foi enviado. |
401 invalid_key | A chave não existe, ou foi revogada. |
403 account_suspended | A conta dona dessa chave está suspensa. |
403 plan_required | A conta está no plano Gratuito — o acesso à API exige Basic, Lite, Pro ou Equipe. |
400 invalid_category | "category" não era "image" nem "document". |
400 missing_target | "target" estava vazio. |
400 no_file | Nenhum arquivo foi enviado, ou o upload falhou — o campo precisa se chamar "file". |
413 file_too_large | O arquivo excede o tamanho máximo de upload do seu plano. |
429 quota_exceeded | A cota mensal de minutos de conversão do plano já foi usada. Reinicia no começo do próximo mês do calendário. |
429 concurrency_limit | Já há conversões demais rodando ao mesmo tempo para essa conta (compartilhado com o site) — espere uma terminar e tente de novo. |
422 conversion_failed | O próprio arquivo não pôde ser convertido — "message" explica o motivo. O código de status varia conforme o motivo: 400/415/422 significam que o arquivo ou o target não vão funcionar não importa quantas vezes você tente de novo; 500/503 significam um problema do lado do servidor, e 503 especificamente vale a pena tentar de novo em pouco tempo. |
Supported formats
Aceito como origem:
JPG, PNG, GIF, WEBP, BMP, AVIF, PDF, PSD, TIFF, EPS, HEIC
Disponível como destino:
JPG, PNG, GIF, WEBP, BMP, AVIF, PDF, ICO, PSD, TIFF, EPS