Fontes de Imagem: URL e Base64
Nesta página
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_idde um ficheiro na API de Ficheiros, como alternativa exclusiva aourl. 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_idda 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