Configuração do Ambiente

Esta página é para quem nunca chamou uma API HTTP pelo terminal antes. Se você já se sente confortável com curl e variáveis de ambiente, vá direto para o Início Rápido.

Instalar um cliente

Você precisa de algo que consiga enviar uma requisição HTTP com cabeçalhos personalizados. Duas opções comuns:

• curl — uma ferramenta de linha de comando, geralmente já instalada no macOS e Linux. Verifique com curl --version no terminal. No Windows, instale via curl.se/windows ou use o curl que vem com o Git Bash / WSL. Todos os exemplos nesta documentação são escritos primeiro como comandos curl.
• Postman (ou Insomnia) — um aplicativo gráfico para criar e salvar requisições, útil se você prefere clicar em um formulário a escrever comandos de shell. Instale-o em postman.com/downloads e, em seguida, recrie qualquer exemplo de curl deste site copiando a URL, o método, os cabeçalhos e o corpo em uma nova requisição.

Usando os exemplos em Python

Todos os exemplos de código neste site têm uma aba Python baseada na popular biblioteca requests — não é um SDK oficial do ImageToTable.ai (não publicamos um; estas são chamadas HTTP simples com qualquer cliente padrão). Você precisa de:

• Python 3.8+ — verifique com python3 --version. Obtenha-o em python.org/downloads se estiver faltando.
• requests — não faz parte da biblioteca padrão, instale-o primeiro:

  pip install requests

  (ou pip3 install requests, dependendo do seu sistema).

Os exemplos de exportação que analisam o arquivo baixado (xlsx/docx) também usam openpyxl / python-docx — só são necessários se você estiver seguindo esses exemplos específicos; instale com pip install openpyxl python-docx.

Usando os exemplos em JavaScript

A aba JavaScript usa a API nativa fetch — nenhuma biblioteca para instalar — mas assume um ambiente de execução razoavelmente atual:

• Node.js 20+ se estiver executando no lado do servidor — verifique com node --version. Os exemplos usam await de nível superior e o crypto.randomUUID() global, ambos exigindo um Node recente; no Node 18 (agora sem suporte), crypto não é confiavelmente global fora do CommonJS/REPL e esses exemplos podem falhar com um erro confuso crypto is not defined que não tem nada a ver com sua chave de API. Obtenha uma versão atual em nodejs.org.
• Ou simplesmente cole o trecho no console DevTools de um navegador — todo navegador moderno suporta as mesmas APIs (fetch, FormData, crypto.randomUUID()) nativamente, sem necessidade de instalação.

Obtenha sua chave de API

Sua chave de API é emitida na página de configurações do perfil da sua conta. A API v1 está disponível para planos pagos (Basic e acima); chamá-la com uma chave do plano Free retorna um erro plan_required em vez de um erro de autenticação ausente, pois a chave em si é válida — ela só não tem permissão para usar a v1 ainda.

Armazene sua chave como uma variável de ambiente

Não cole sua chave diretamente em um comando que você possa compartilhar, capturar de tela ou enviar para o controle de versão. Exporte-a para sua sessão do shell e faça referência a ela como $API_KEY em cada requisição — todo exemplo neste site assume que essa variável existe:

export API_KEY="itt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Isso dura apenas para a sessão atual do terminal. Para algo mais permanente, adicione a mesma linha ao arquivo de inicialização do seu shell (~/.bashrc, ~/.zshrc ou equivalente) — ou, se estiver escrevendo um script, carregue-a de um arquivo .env / gerenciador de segredos em vez de codificá-la diretamente no código-fonte.

Enviar uma solicitação de teste

Confirme sua chave e configuração antes de passar para documentos reais:

curl https://imagetotable.ai/api/v1/account \
  -H "Authorization: Bearer $API_KEY"

Uma chave funcional em um plano pago retorna um resumo da sua conta (plano, função, créditos disponíveis). Qualquer outra coisa, veja a lista de verificação de solução de problemas abaixo.

Lista de verificação de solução de problemas

Todo erro da v1 retorna como JSON com type/code/message — consulte o guia completo de Tratamento de Erros para a lista completa. As verificações mais rápidas para uma solicitação que não está funcionando:

• Recebendo missing_api_key? Verifique se o cabeçalho está exatamente Authorization: Bearer <key> — a palavra Bearer, um espaço simples e a chave. Um espaço faltando ou um caractere de aspas extra em $API_KEY produzem isso.
• Recebendo invalid_api_key? A chave não corresponde a nenhuma conta, ou a conta está desabilitada. Copie-a novamente da sua página de perfil — as chaves são longas e fáceis de truncar ao copiar e colar.
• Recebendo plan_required? Sua chave é válida, mas sua conta está no plano Free. Faça upgrade para o plano Basic ou superior para usar a v1.
• Recebendo um erro de conexão, não uma resposta JSON? Verifique novamente se a URL começa com https://imagetotable.ai/api/v1/ e se você está usando -X POST (ou o verbo correto) para endpoints que exigem isso — uma solicitação GET para um endpoint somente POST não alcançará a rota.
• Enviando um arquivo e recebendo um erro inesperado? Uploads de arquivos multipart precisam de -F "file=@/caminho/para/arquivo.jpg" (a flag de upload de formulário do curl), não -d ou um corpo JSON bruto — misturar esses é o erro de upload mais comum. O @ inicial diz ao curl para ler aquele caminho como um arquivo real na sua própria máquina — não é uma URL, e o arquivo já precisa existir lá antes de você executar o comando. Se você não tiver um arquivo local disponível, pule isso completamente: passe um campo url em vez de file e o servidor o buscará para você — veja Quickstart.
• Recebendo rate_limit_exceeded? Veja Limites de Taxa — os limites são por conta, não por tipo de solicitação que você espera, então uma rajada de chamadas de polling pode acionar o mesmo limite que uma rajada de uploads.