Como converter imagens para Base64 para requisições de Vision API

Por que Vision APIs precisam de Base64

Vision APIs modernas como OpenAI GPT-4o, Google Cloud Vision, Anthropic Claude e Qwen-VL aceitam imagens de duas formas: uma URL pública apontando para a imagem ou os dados brutos da imagem codificados como uma string Base64 diretamente no corpo da requisição JSON.

Se sua imagem já está hospedada online, a abordagem por URL é simples. Mas no trabalho real, as imagens frequentemente são locais: uma captura de tela recém-tirada, um documento digitalizado, um frame extraído de um vídeo, uma imagem de teste do pipeline de desenvolvimento. Nesses casos, a codificação Base64 é a opção ideal — você pode incluir a imagem diretamente na requisição da API sem precisar fazer upload em um servidor primeiro.

Uma requisição típica de Vision API com Base64 se parece com isto:

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What's in this image?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgo..."
          }
        }
      ]
    }
  ]
}

O desafio está em gerar essa string Base64 a partir de um arquivo local — especialmente quando você precisa repetir isso várias vezes durante o desenvolvimento e os testes.

Métodos comuns (e suas desvantagens)

1. Script Python

import base64

with open("screenshot.png", "rb") as f:
    encoded = base64.b64encode(f.read()).decode()
print(encoded)

Funciona bem, mas exige que o Python esteja instalado, que você escreva (ou encontre) o script e copie a saída do terminal. Para testes repetidos com imagens diferentes, você precisa executar o script novamente e colar a saída manualmente no JSON a cada vez.

2. Linha de comando

# macOS / Linux
base64 -i screenshot.png | pbcopy

# Windows PowerShell
[Convert]::ToBase64String([IO.File]::ReadAllBytes("screenshot.png")) | Set-Clipboard

Rápido se você lembrar da sintaxe, mas a saída é apenas uma string. Não há como confirmar se é a imagem correta ou se a codificação está certa. Você só descobre ao enviar a requisição para a API e verificar o resultado.

3. Conversores Base64 online

Muitos sites oferecem conversão de arquivo para Base64 via arrastar e soltar. O problema óbvio: você precisa fazer upload do arquivo para o servidor de outra pessoa. Para capturas de tela de teste pode ser aceitável, mas para dados proprietários, documentos internos, imagens médicas ou arquivos sob NDA, não é uma opção.

Uma abordagem melhor: colar, pré-visualizar, copiar

O ViewJSON oferece um fluxo de trabalho mais simples. Cole a imagem diretamente no editor e obtenha a string Base64 instantaneamente, com tudo processado dentro do navegador:

1. Abra o ViewJSON — acesse viewjson.net
2. Cole a imagem — copie a imagem do explorador de arquivos, ferramenta de captura de tela, navegador, app de design ou qualquer lugar e cole diretamente no editor JSON com Ctrl+V
3. Confira a pré-visualização — o ViewJSON converte automaticamente a imagem para Base64 e a insere como valor de string no JSON. A pré-visualização inline da imagem aparece instantaneamente para que você confirme que é a imagem correta.
4. Copie o Base64 — clique no botão de copiar ou selecione o valor da string. Você obtém a string Base64 completa pronta para ser colada no payload da sua requisição de API.

Veja a demo completa do fluxo de trabalho:

Lidando com strings Base64 grandes

Imagens codificadas em Base64 podem ser muito longas. Um único JPEG em alta resolução pode gerar uma string com mais de 100.000 caracteres. Para manter o editor responsivo, o ViewJSON trunca automaticamente a exibição de strings longas. Porém, o truncamento é apenas visual.

Quando você copia um valor Base64 truncado, o mecanismo de restauração lossless da área de transferência do ViewJSON entra em ação. Ele detecta que você está copiando uma string truncada e restaura automaticamente o conteúdo original completo na área de transferência. Você sempre obtém a string Base64 completa e intacta, não uma versão truncada que geraria um arquivo corrompido.

Montando o payload completo da API

Depois de obter a string Base64, você precisa inseri-la no formato correto da API. Veja exemplos das Vision APIs mais populares:

OpenAI GPT-4o Vision

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Describe this image" },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,<YOUR_BASE64_HERE>"
          }
        }
      ]
    }
  ],
  "max_tokens": 300
}

Google Cloud Vision

{
  "requests": [
    {
      "image": {
        "content": "<YOUR_BASE64_HERE>"
      },
      "features": [
        { "type": "TEXT_DETECTION" }
      ]
    }
  ]
}

Depois de colar a imagem no ViewJSON, copie a string Base64 gerada e insira no payload da requisição da API. Você também pode usar o construtor de requisições API do ViewJSON para configurar URL, método, cabeçalhos e corpo, e exportar a requisição completa como comando cURL.

Privacidade: sem uploads

Diferente dos sites conversores de Base64 online, o ViewJSON roda inteiramente no navegador. A conversão de imagem para Base64 é feita localmente usando a API FileReader nativa do navegador. Nenhuma imagem é enviada para nenhum servidor.

Isso o torna adequado para conversão de imagens sensíveis: exames médicos para APIs de saúde, documentos internos para serviços de OCR, imagens proprietárias de produtos para sistemas de busca visual ou qualquer arquivo que você não queira enviar para um conversor de terceiros.

Comparação de métodos