API de conversão de arquivos

Converta arquivos a partir do seu próprio código com os mesmos conversores do site: uma chave de API, uma interface REST simples, créditos e webhooks.

Início rápido

Crie uma chave na página da sua conta e envie um arquivo e o formato desejado:

curl -X POST https://api.101convert.com/v1/conversions \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@photo.jpg" \
  -F "target=webp" \
  -F "quality=85" \
  -F "wait=30"

A resposta descreve a conversão. Com wait=30 uma conversão rápida já fica pronta na mesma resposta; caso contrário, consulte o status depois. Em seguida baixe o resultado:

{
  "id": "cnv_01j9z3k8q4x7m2n5p6r8s9t0v1",
  "status": "succeeded",
  "source": "jpg",
  "target": "webp",
  "credits": 2,
  "result": {
    "filename": "photo.webp",
    "size": 48213,
    "download_url": "https://api.101convert.com/v1/conversions/cnv_01j9z3k8q4x7m2n5p6r8s9t0v1/download",
    "expires_at": "…"
  }
}

curl -o photo.webp -H "Authorization: Bearer $API_KEY" \
  https://api.101convert.com/v1/conversions/cnv_01j9z3k8q4x7m2n5p6r8s9t0v1/download

Autenticação

Envie sua chave no cabeçalho Authorization como "Bearer ". As chaves são criadas e revogadas na página da sua conta e mostradas só uma vez. Mantenha-as em segredo: qualquer pessoa com sua chave pode gastar seus créditos.

Endpoints

Entrada, opções e formatos

Envie o arquivo como campo multipart "file" ou um link público como "url" (nossos servidores o baixam). O formato de origem é obtido do nome do arquivo; se não houver, envie "source". Opções como a qualidade podem ser enviadas como campos simples (quality=85) ou como options[quality]=85. GET /v1/formats/{source} lista todos os formatos de destino com opções e limites.

curl -X POST https://api.101convert.com/v1/conversions \
  -H "Authorization: Bearer $API_KEY" \
  -d "url=https://example.com/report.docx" \
  -d "target=pdf"

curl -H "Authorization: Bearer $API_KEY" https://api.101convert.com/v1/formats/jpg

Aguardando o resultado

As conversões são processadas em fila. Consulte GET /v1/conversions/{id} até o status ser succeeded ou failed, aguarde até 30 segundos na própria solicitação com wait=30, ou envie uma callback_url e avisaremos você. Um resultado pode ser baixado várias vezes por 24 horas.

Créditos e limites

Uma conversão custa os mesmos créditos que no site: o peso do tipo de conversão vezes a faixa de tamanho do arquivo, e só quando dá certo. Planos pagos usam seus créditos mensais. Uma conta gratuita recebe 100 créditos gratuitos de API todo mês.

Uma resposta 429 traz o cabeçalho Retry-After. As conversões também contam para o limite do seu plano de conversões a cada 10 minutos, compartilhado com o site.

Comparar planos

Webhooks

Com uma callback_url (só https) enviamos um POST com a conversão em JSON quando ela termina. Verifique o cabeçalho X-101convert-Signature: ele contém t, um horário Unix, e v1, o HMAC-SHA256 de "t.body" feito com o segredo de webhooks da página da sua conta. Rejeite carimbos de tempo antigos para evitar repetições. Entregas que falham são repetidas por cerca de uma hora e meia.

// PHP
[$t, $v1] = array_map(fn ($p) => explode('=', $p, 2)[1],
    explode(',', $_SERVER['HTTP_X_101CONVERT_SIGNATURE']));
$body  = file_get_contents('php://input');
$valid = abs(time() - (int) $t) < 300
    && hash_equals(hash_hmac('sha256', "$t.$body", $webhookSecret), $v1);

// Node.js
const [t, v1] = req.headers['x-101convert-signature'].split(',').map(p => p.split('=')[1]);
const expected = crypto.createHmac('sha256', webhookSecret).update(`${t}.${rawBody}`).digest('hex');
const valid = Math.abs(Date.now() / 1000 - t) < 300
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));

Repetições seguras

Envie um cabeçalho Idempotency-Key com um valor único seu. Se a solicitação for repetida, por exemplo após um tempo esgotado, você recebe a conversão original em vez de uma nova e paga só uma vez.

curl -X POST https://api.101convert.com/v1/conversions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: invoice-2026-0042" \
  -F "file=@invoice.docx" -F "target=pdf"

Erros

Todos os erros têm o mesmo formato. Decida com base em code, que nunca muda; message é para pessoas e segue o cabeçalho Accept-Language.

{
  "error": {
    "code": "file_too_large",
    "message": "…",
    "details": { "max_upload_mb": 60 }
  }
}

Exemplos

# Python
import requests, time

API = "https://api.101convert.com/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

with open("interview.mp3", "rb") as f:
    c = requests.post(f"{API}/conversions", headers=headers,
                      files={"file": f}, data={"target": "docx"}).json()

while c["status"] not in ("succeeded", "failed"):
    time.sleep(5)
    c = requests.get(c["links"]["self"], headers=headers).json()

if c["status"] == "succeeded":
    open("interview.docx", "wb").write(
        requests.get(c["result"]["download_url"], headers=headers).content)

// PHP (Laravel)
$c = Http::withToken($apiKey)
    ->attach('file', fopen('slides.pptx', 'r'), 'slides.pptx')
    ->post('https://api.101convert.com/v1/conversions', ['target' => 'pdf', 'wait' => 30])
    ->json();

if ($c['status'] === 'succeeded') {
    file_put_contents('slides.pdf', Http::withToken($apiKey)->get($c['result']['download_url'])->body());
}

// JavaScript (Node 18+)
const form = new FormData();
form.append('file', new Blob([await fs.promises.readFile('scan.png')]), 'scan.png');
form.append('target', 'pdf');
form.append('callback_url', 'https://example.com/hooks/101convert');

const res = await fetch('https://api.101convert.com/v1/conversions', {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
  body: form,
});
const conversion = await res.json(); // status "queued"; the webhook follows