Desenvolvimento com APIs de Visão: Como converter imagens locais para Base64

Por que as 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 tem esta estrutura:

{
  "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 de 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 aparece instantaneamente.
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 o 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. Você sempre obtém a string Base64 completa e intacta.

Montando o payload completo da API

Depois de obter a string Base64, você precisa inseri-la no formato correto da API. Aqui estão exemplos para as principais Vision APIs:

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 como comando cURL.

Privacidade: sem uploads

Diferente dos sites conversores de Base64 online, o ViewJSON roda inteiramente no navegador. A conversão usa a API FileReader nativa. 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 ou qualquer arquivo que você não queira enviar para um conversor de terceiros.

Comparação de métodos