Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Fontes de Imagem: URL e Base64

Aula 6 de 14 Atualizada a 3 de novembro de 2026 Iniciante
Nesta página
  1. Fornecer Imagens ao Endpoint de Edição
  2. Formato URL
  3. Formato Data URI Base64
  4. Terceira Opção: Um Ficheiro da API de Ficheiros
  5. Função de Utilidade
  6. Prática Prática
  7. Pontos-chave

Atualizado em 3 de novembro de 2026. Com base na página Image Editing e na referência da API de Imagens da xAI: uma imagem de origem também pode ser especificada utilizando o file_id de um ficheiro na API de Ficheiros, como alternativa exclusiva ao url. Fontes: Image Editing · Images API.

Fornecer Imagens ao Endpoint de Edição

O endpoint de edição aceita imagens de origem em três formatos: um URL público, um Data URI Base64 ou o file_id de um ficheiro já carregado na API de Ficheiros da xAI. Cada um tem os seus casos de uso; dominá-los permite-lhe criar pipelines de edição flexíveis.

Formato URL

O formato URL é a opção mais conveniente, desde que a imagem já esteja online: nada para codificar, uma carga útil diminuta e um pedido que permanece legível nos registos. A restrição fundamental aqui é público — a imagem deve ser recuperável pelos servidores da xAI sem sessão nem token.

payload = {
    "model": "grok-imagine-image",
    "prompt": "Add a gold frame around this image",
    "image": {
        "url": "https://exemple.com/ma-photo.jpg"
    }
}

Restrições do URL

  • O URL deve ser publicamente acessível (sem links protegidos por autenticação)
  • Os formatos suportados são JPEG, PNG e WebP
  • A imagem deve ser acessível rapidamente (evite servidores lentos)

Utilizar URLs de Saída da API

É isto que torna a edição em várias passagens prática: a saída de uma edição torna-se a entrada da seguinte, sem nunca descarregar a imagem para a sua máquina local. Uma ressalva, no entanto: estes URLs expiram, pelo que a cadeia deve ser executada de uma só vez. Para um fluxo de trabalho distribuído ao longo do tempo, descarregue-a entre cada passo.

import requests
import os

headers = {
    "Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
    "Content-Type": "application/json"
}

# Gerar uma imagem
gen_response = requests.post(
    "https://api.x.ai/v1/images/generations",
    headers=headers,
    json={
        "model": "grok-imagine-image",
        "prompt": "A medieval castle on a hill"
    }
).json()

generated_url = gen_response["data"][0]["url"]

# Editar a imagem gerada
edit_response = requests.post(
    "https://api.x.ai/v1/images/edits",
    headers=headers,
    json={
        "model": "grok-imagine-image",
        "prompt": "Add a dragon flying over the castle",
        "image": {"url": generated_url}
    }
).json()

Formato Data URI Base64

Para imagens armazenadas localmente ou geradas dinamicamente, utilize o formato Data URI Base64:

import base64

# Ler uma imagem local
with open("photo_locale.jpg", "rb") as f:
    image_bytes = f.read()

b64_string = base64.b64encode(image_bytes).decode("utf-8")
data_uri = f"data:image/jpeg;base64,{b64_string}"

payload = {
    "model": "grok-imagine-image",
    "prompt": "Transform this photo into a vector illustration",
    "image": {
        "url": data_uri
    }
}

Quando Utilizar Base64?

O critério é simples: o Base64 é necessário sempre que utilizar um URL público constitua um desvio desnecessário. Isto aplica-se a imagens locais que não estão alojadas em lado nenhum — carregá-las para um servidor apenas para as tornar acessíveis à API adiciona um passo e um atraso sem valor. Aplica-se também a imagens geradas na memória pela sua aplicação: um gráfico produzido em tempo real, uma captura de ecrã de uma renderização ou uma miniatura composta dinamicamente nunca precisam de tocar no disco. O Base64 resolve também uma questão de privacidade — uma imagem codificada no corpo do pedido nunca fica exposta num servidor público, mesmo que temporariamente — e simplifica a arquitetura: um pipeline automatizado que encadeia geração, edição e gravação funciona de ponta a ponta sem alojamento intermédio para provisionar, proteger e limpar.

Atenção ao Tamanho

O Base64 inflaciona a carga útil em cerca de um terço, o que é negligenciável para uma miniatura, mas torna-se significativo para uma fotografia de vários megabytes — tempos de carregamento mais longos e risco de exceder os limites de tamanho do pedido. A regra prática: se a imagem já estiver acessível online, utilize o URL; se for local, o Base64 é mais simples do que alojá-la apenas para a ocasião.

Terceira Opção: Um Ficheiro da API de Ficheiros

Uma imagem já carregada na API de Ficheiros da xAI é especificada pelo seu identificador, em vez de um URL. Os dois campos são mutuamente exclusivos: um objeto image contém quer url quer file_id.

payload = {
    "model": "grok-imagine-image",
    "prompt": "Add snow to the landscape",
    "image": {"file_id": "file_abc123"}
}

Esta é a escolha natural para uma imagem reutilizada em várias edições: é enviada apenas uma vez e não precisa de ser pública.

Função de Utilidade

Eis uma função que gere ambos os formatos automaticamente:

import base64
import os

def prepare_image_source(source):
    """Prepares an image source for the API (URL or local file)."""
    if source.startswith("http://") or source.startswith("https://"):
        return {"url": source}

    if os.path.isfile(source):
        ext = source.rsplit(".", 1)[-1].lower()
        mime_map = {"jpg": "jpeg", "jpeg": "jpeg", "png": "png", "webp": "webp"}
        mime_type = mime_map.get(ext, "jpeg")

        with open(source, "rb") as f:
            b64 = base64.b64encode(f.read()).decode("utf-8")
        return {"url": f"data:image/{mime_type};base64,{b64}"}

    raise ValueError(f"Invalid source: {source}")

Esta função deteta automaticamente se a origem é um URL ou um caminho de ficheiro local e formata o objeto em conformidade.

Prática Prática

Teste ambos os formatos com a mesma imagem e prompt para verificar que ambos os caminhos funcionam; as imagens resultantes variarão de execução para execução, como em qualquer geração:

# Via URL
payload_url = {
    "model": "grok-imagine-image",
    "prompt": "Add snow to the landscape",
    "image": {"url": "https://exemple.com/paysage.jpg"}
}

# Via Base64
payload_b64 = {
    "model": "grok-imagine-image",
    "prompt": "Add snow to the landscape",
    "image": prepare_image_source("paysage.jpg")
}

Pontos-chave

  • Três formas de entrada: URL público, Data URI Base64 ou file_id da API de Ficheiros
  • URLs temporários devolvidos pela API podem servir como fontes de edição
  • O Base64 aumenta o tamanho da carga útil em ~33%
  • Crie uma função de utilidade para gerir ambos os formatos automaticamente
  • O URL deve ser publicamente acessível para funcionar