Saltar para o conteúdo principal
0Entrar

REST API

Imagem, PDF e processamento de arquivos API

Todos os processadores de arquivos compartilham um ponto final de trabalho. Escolha a operação com o toolName; encontre parâmetros e exemplos completos para cada ferramenta abaixo.

1. Criar uma chave API
  1. Registre-se, verifique seu e-mail e entre em uma conta gratuita.
  2. Abrir configurações → chaves API (também disponível no menu do usuário), digite um nome e crie uma chave.
  3. A chave completa é mostrada uma vez. Copie- a para a sua variável de ambiente API_KEY do lado do servidor. Revogue e substitua uma chave perdida.
Authorization: Bearer $API_KEY

Os envios, trabalhos, pesquisas, downloads e gerenciamento de regras requerem uma chave API válida ou uma sessão da Web iniciada. Use uma chave API para scripts, MCP e automação; nunca coloque-a no código de frontend. Chaves renovadas param de funcionar imediatamente.

Cada chave permite até o 120 requisições/minuto por padrão, incluindo votação. As quotas de trabalho são compartilhadas em toda a conta e chaves: predefinições gratuitas para 20/dia, Pro para 100/dia. Leia GET /api/tools/entitlements para configuração real.

2. Upload → criar trabalho → enquete → download
Pedido Entrada / resposta
POST /api/tools/files arquivo de campo multiparte → data.file.id; um arquivo por upload
POST /api/tools/jobs{toolName, input: {fileId / fileIds, execution: "async", …}} → data.job.id
GET /api/tools/jobs?id=JOB_IDdata.job.status + data.job.result
GET /api/tools/artifacts?id=ARTIFACT_ID&download=1Download binário autenticado; ID em data.job.result.data.artifact.id
DELETE /api/tools/jobs?id=JOB_ID Cancelar uma tarefa pendente; as tarefas de terminal poderão retornar o 409

O HTTP 202 (status: aceita) não está completo. Pesquise todos os segundos do 2 até que data.job.status esteja concluído, falhou, cancelou ou expirou. Leia os dados de sucesso em data.job.result.data e detalhes de falha em data.job.result.error.details. Inspection retorna JSON sem um arquivo de download.

modo: must_pass requer que cada regra passe; best_effort pode retornar um candidato com avisos. Envie regras em linha ou um ruleId salvo, nunca ambos. Ferramentas de imagem única aceitam um fileId por trabalho; crie um trabalho por imagem.

Os envios e artefatos normalmente duram 24 horas; use expiresAt. Defina a chave de ideologia na criação de emprego e reutilize-o com o mesmo corpo após falhas de rede. Trabalhos livres permitem 25 MB combinado, páginas 100, 40 MP e até entradas 10. Pro permite entradas 100; os limites do motor ainda se aplicam.

3. Parâmetros e exemplos por ferramenta

Verificar arquivo antes do envio · validate_file
POST /api/tools/validate

O arquivo contém fatos e regras fornecidos contém restrições. Nenhum bytes é carregado ou inspecionado. O ruleId salvo requer autenticação.

{
  "file": {
    "name": "example.png",
    "mimeType": "image/png",
    "bytes": 180000
  },
  "rules": {
    "maxBytes": 200000
  },
  "mode": "must_pass"
}
Abra a ferramenta e gere o código do seu formulário
Comprimir imagem para 200KB · compress_image
POST /api/tools/jobs

fileId, targetBytes (bytes), formato, allowDownscale; regras.maxBytes pode validar a saída.

{
  "toolName": "compress_image",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "format": "jpeg",
    "targetBytes": 200000,
    "allowDownscale": true,
    "execution": "async"
  }
}
Abra a ferramenta e gere o código do seu formulário
Converter imagens · convert_image
POST /api/tools/jobs

fileId, formato; fundo opcional (# RRGGBB) e dpi (JPEG/PNG apenas).

{
  "toolName": "convert_image",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "format": "webp",
    "execution": "async"
  }
}
Abra a ferramenta e gere o código do seu formulário
Redimensionar imagens · resize_image
POST /api/tools/jobs

fileId, pelo menos uma de largura/altura (pixels), ajuste (contém/cobre), allowUpscale, formato, dpi.

{
  "toolName": "resize_image",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "width": 1200,
    "fit": "contain",
    "allowUpscale": false,
    "format": "jpeg",
    "execution": "async"
  }
}
Abra a ferramenta e gere o código do seu formulário
Recortar imagens · crop_image
POST /api/tools/jobs

fileId, corte: {x,y,width,height} em pixels do canto superior esquerdo; formato seleciona o tipo de saída.

{
  "toolName": "crop_image",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "crop": {
      "x": 0,
      "y": 0,
      "width": 200,
      "height": 200
    },
    "format": "png",
    "execution": "async"
  }
}
Abra a ferramenta e gere o código do seu formulário
Remover fundo · remove_background
POST /api/tools/jobs

Remova o fundo e baixe um PNG transparente.

{
  "toolName": "remove_background",
  "input": {
    "fileId": "FILE_ID",
    "execution": "async"
  }
}
Abra a ferramenta e gere o código do seu formulário
Inspecionar imagens · inspect_image
POST /api/tools/jobs

fileId; retorna dimensões decodificadas, DPI e fatos EXIF/GPS. Sem artefato de download.

{
  "toolName": "inspect_image",
  "input": {
    "fileId": "FILE_ID",
    "execution": "async"
  }
}
Abra a ferramenta e gere o código do seu formulário
Imagens para PDF · convert_image_to_pdf
POST /api/tools/jobs

fileIds em ordem de página; pageSize (original/a4/letter), pageOrientation (retrato/paisagem), marginPoints (0–144 pt), pageDpi (36–600).

{
  "toolName": "convert_image_to_pdf",
  "input": {
    "fileIds": [
      "FILE_ID_1",
      "FILE_ID_2"
    ],
    "mode": "best_effort",
    "pageSize": "a4",
    "pageOrientation": "portrait",
    "marginPoints": 24,
    "pageDpi": 150,
    "execution": "async"
  }
}
Abra a ferramenta e gere o código do seu formulário
Inspecionar PDF · inspect_file
POST /api/tools/jobs

O fileId; devolve as páginas, dimensões, fontes e factos de imagem incorporados do PDF. Não existe nenhum artefacto de transferência.

{
  "toolName": "inspect_file",
  "input": {
    "fileId": "FILE_ID",
    "execution": "async"
  }
}
Abra a ferramenta e gere o código do seu formulário
Comprimir PDF para 200KB · compress_pdf
POST /api/tools/jobs

fileId; regras.maxBytes define o alvo em bytes. O modo rígido falha com um relatório de regras se o alvo não puder ser atingido.

{
  "toolName": "compress_pdf",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "rules": {
      "maxBytes": 200000
    },
    "execution": "async"
  }
}
Abra a ferramenta e gere o código do seu formulário
Juntar PDFs · merge_pdfs
POST /api/tools/jobs

fileIds, pelo menos 2, fundiu-se em ordem de array; regras opcionais validam o resultado.

{
  "toolName": "merge_pdfs",
  "input": {
    "fileIds": [
      "FILE_ID_1",
      "FILE_ID_2"
    ],
    "mode": "best_effort",
    "execution": "async"
  }
}
Abra a ferramenta e gere o código do seu formulário
Extrair páginas PDF · split_pdf
POST /api/tools/jobs

fileId, pageRange (por exemplo, 1-3,5,2) ou array de páginas; os números de página começam em 1 e podem ser reordenados ou repetidos.

{
  "toolName": "split_pdf",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "pageRange": "1-2",
    "execution": "async"
  }
}
Abra a ferramenta e gere o código do seu formulário
Girar páginas PDF · rotate_pdf
POST /api/tools/jobs

fileId, rotação (90/180/270); opcional pageRange/pages, omitido para rodar todas as páginas.

{
  "toolName": "rotate_pdf",
  "input": {
    "fileId": "FILE_ID",
    "mode": "best_effort",
    "rotation": 90,
    "pageRange": "1",
    "execution": "async"
  }
}
Abra a ferramenta e gere o código do seu formulário
Pacote ZIP para envio · create_submission_package
POST /api/tools/jobs

fileIds, packageName, namingTemplate; modelo livre: {index}-{name}.{ext}. Modelos personalizados requerem Pro. ZIP inclui relatórios de arquivos, manifestos e por arquivo.

{
  "toolName": "create_submission_package",
  "input": {
    "fileIds": [
      "FILE_ID_1",
      "FILE_ID_2"
    ],
    "mode": "best_effort",
    "packageName": "submission-package",
    "namingTemplate": "{index}-{name}.{ext}",
    "execution": "async"
  }
}
Abra a ferramenta e gere o código do seu formulário
Erros, permissões e integrações

401: chave em falta, inválida ou revogada. 403: conta/chave não possui permissão. 429 / rate_limited: taxa de solicitação ou quota diária atingida; recuar apenas quando é permitido repetir a tentativa. invalid_input: parâmetros de verificação. subscription_required: capacidade de plano necessária. processing_failed/falso de regras: inspecionar error.details. Polling HTTP 200 sozinho não significa que o processamento foi bem- sucedido.

O catálogo, OpenAPI e os fatos fornecidos /api/tools/validate endpoint são públicos. O processamento da web de hóspedes tem um caminho separado sessão/IP-limitada, não credenciais de automação anônimas. Arquivos, trabalhos, regras e artefatos são controlados pelo proprietário.

Use /api/tools/rules (GET/POST/DELETE) para regras salvas e GET /api/tools/jobs para o histórico. OpenAPI contém esquemas completos. MCP e ferramentas de compartilhamento REST e quotas de conta. O checkout e os backups do Pro ainda não estão abertos.

OpenAPI 3.1MCP Catálogo legível por máquina
# CLI: ATTACHREADY_BASE_URL + ATTACHREADY_API_KEY
node scripts/tools-cli.mjs run convert_image --input '{"fileId":"FILE_ID","format":"webp"}' --wait