API para desenvolvedores

Uma API universal para todos os fluxos de trabalho com arquivos

Converter App oferece aos desenvolvedores uma interface de processamento de arquivos de alto desempenho. Substitua ferramentas separadas por uma única API para conversão de documentos, processamento de mídia, transcrição e OCR escaláveis.

Obter acesso

Visão geral da API do Converter App

A API do Converter App oferece aos desenvolvedores uma interface universal e sem atritos para todas as necessidades de processamento de arquivos. Em vez de integrar um conjunto fragmentado de ferramentas separadas, seu aplicativo pode chamar um único serviço de alto desempenho. Você pode integrar nossa suíte completa de conversão diretamente aos fluxos de trabalho de backend para lidar com tudo, desde conversões de arquivos padrão até tarefas exigentes de mídia.

A URL base pública é https://api.converter.app/. Os caminhos neste documento usam essa raiz de API disponibilizada externamente.

Cobertura universal

Acesse uma biblioteca completa de ferramentas de conversão por meio de uma integração simplificada.

Dois modos de processamento

Escolha requisições síncronas para respostas imediatas ou tarefas assíncronas para arquivos grandes e tarefas de longa duração.

Adaptado às Suas Necessidades

Entre em contato e podemos oferecer um plano personalizado para as suas necessidades, com uma taxa imbatível.

Documentos Imagens Áudio Vídeo Texto Arquivos compactados

Descubra as conversões compatíveis (não é necessária nenhuma chave)

Use o endpoint público de pares como o teste de conectividade mais simples. Ele não requer uma chave de API e retorna a lista completa de pares de conversão compatíveis disponíveis na plataforma.

OBTER /public/pairs

Este endpoint é aberto para que os desenvolvedores possam inspecionar o catálogo universal de conversão antes de solicitar ou configurar uma chave de 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'])

Resposta de exemplo

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

Autenticação & Controle de Acesso

Os desenvolvedores autenticam-se passando sua chave de API no cabeçalho HTTP X API Key. O endpoint público /public/pairs é o único endpoint nesta página que não exige uma chave.

Controle	Como funciona	Impacto para desenvolvedores
`X-API-Key`	Envie a chave como um cabeçalho da solicitação HTTP.	Obrigatório para `/pairs`, `/convert/sync`, `/convert`, `/progress/{jobid}` e `/download/{jobid}`.
Cotas de uso	Cada chave tem uma cota numérica de conversão. A cota diminui quando tarefas de conversão são criadas.	Uma cota de `-1` concede conversões ilimitadas. Outros valores representam as conversões restantes permitidas.
Pares permitidos	As chaves podem ser restritas a tipos específicos de conversão, como `mp42mp3`, ou receber acesso a `all` os pares suportados.	`/pairs` retorna apenas os pares que sua chave está autorizada a usar, e as solicitações de conversão fora dessa lista são rejeitadas.

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. Conversão síncrona

POST /convert/sync

Use a conversão síncrona quando desejar um resultado imediato na mesma resposta HTTP. A solicitação permanece aberta enquanto a API inicia a tarefa de conversão e aguarda a conclusão, por até 30 minutos.

Campo de formulário	Tipo	Descrição
`target_format`	string	A extensão de saída solicitada, como `pdf`, `docx`, `mp3` ou `jpg`.
`files`	file[]	Um ou mais arquivos-fonte enviados. A API determina o formato de origem a partir do nome do arquivo enviado.

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)

A resposta transmite diretamente o arquivo convertido em fluxo. Se a conversão produzir vários arquivos, a API retorna um arquivo .zip.

3. Conversão assíncrona

POST /convert

Use a conversão assíncrona para arquivos grandes, processamento em lote, tarefas de áudio ou vídeo de longa duração ou aplicações de produção que não devem manter as solicitações de upload abertas enquanto o processamento está em andamento.

Campo do formulário	Tipo	Descrição
`target_format`	string	O formato de saída desejado. A origem e o destino formam o par de conversão, por exemplo `mp42mp3`.
`files`	arquivo[]	Um ou mais arquivos para converter.

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'])

Resposta de sucesso

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

4. Rastreamento de status

OBTER /progress/{jobid}

Consulte este endpoint após criar um trabalho assíncrono. Ele retorna o status do trabalho, um valor numérico de progresso de 0.0 a 1.0 e detalhes do erro se a conversão falhar.

Cabeçalho	Descrição
`X-API-Key`	Sua chave de API de desenvolvedor.

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
}

Os status possíveis são processing, completed e failed. O progresso é um número entre 0.0 e 1.0.

5. Recuperação de Arquivos

OBTER /download/{jobid}

Quando um job assíncrono atingir completed, recupere o arquivo de saída convertido com a mesma chave de API usada para criar o job.

Tipo de resultado	Comportamento
Arquivo de saída único	A API transmite o arquivo convertido diretamente.
manifesto de `resultfile`	Se o trabalho fornecer um manifesto de resultado, a API retorna o arquivo especificado por esse manifesto.
Vários arquivos de saída	Os pacotes da API agrupam os arquivos em um arquivo `.zip` em tempo real.

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)

Resumo do fluxo de trabalho do desenvolvedor

A API oferece suporte a dois padrões de integração, para que os desenvolvedores possam escolher o comportamento certo para cada caso de uso.

Fluxo	Padrão de solicitação	Ideal para
Fluxo Rápido de Sincronização	`POST /convert/sync` retorna o arquivo convertido na mesma resposta.	Arquivos pequenos, scripts de linha de comando, protótipos e automações simples no lado do servidor.
Fluxo assíncrono robusto	`POST /convert`, depois consulte periodicamente `GET /progress/{jobid}` e, em seguida, chame `GET /download/{jobid}`.	Arquivos de vídeo ou áudio grandes, conversão em lote, backends de aplicativos web e sistemas de produção com suporte a novas tentativas.

Exemplo de fluxo assíncrono

# 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)

Respostas de erro

Os erros são retornados como JSON com um campo detail, usando códigos de status HTTP padrão.

Status	Causa comum
`400`	Arquivos ausentes, `target_format` ausente, formato de ID de tarefa não suportado ou entrada da solicitação inválida.
`401`	Chave `X API Key` ausente ou inválida.
`403`	A chave da API não tem permissão para usar o par de conversão solicitado.
`404`	O trabalho solicitado ou o arquivo de resultado gerado não está disponível.
`409`	A conversão ainda está em processamento quando é solicitada uma transferência.
`429`	A chave da API não tem cota restante.
`500`	A conversão não pôde ser preparada nem concluída devido a um erro de processamento no servidor.

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

Uma API universal para todos os fluxos de trabalho com arquivos

Visão geral da API do Converter App

Descubra as conversões compatíveis (não é necessária nenhuma chave)

JavaScript

Python

Resposta de exemplo

Autenticação & Controle de Acesso

JavaScript

Python

2. Conversão síncrona

JavaScript

Python

3. Conversão assíncrona

cURL

JavaScript

Python

Resposta de sucesso

4. Rastreamento de status

JavaScript

Python

5. Recuperação de Arquivos

JavaScript

Python

Resumo do fluxo de trabalho do desenvolvedor

Exemplo de fluxo assíncrono

JavaScript

Python

Respostas de erro

Privacidade e termos

Contact