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

URLs temporárias e estratégias de transferência

Aula 13 de 14 Atualizada a 3 de novembro de 2026 Iniciante
Nesta página
  1. Gestão de imagens geradas efémeras
  2. O problema dos URLs temporários
  3. Estratégia 1: Transferência imediata
  4. Estratégia 2: Utilização de Base64
  5. Estratégia 3: Armazenamento automático na nuvem
  6. Estratégia 4: Deixar a xAI armazenar a imagem
  7. Pipeline robusto com repetição
  8. Boas práticas
  9. Pontos-chave

Lição concluída em 3 de novembro de 2026 com base nas páginas Image Generation e Imagine outputs da xAI: o parâmetro storage_options mantém a imagem na API de Ficheiros e pode criar um URL público permanente; a documentação não especifica a duração de vida dos URLs efémeros (os “erros 403 ou 404” da versão anterior não aparecem aqui); as imagens são produzidas em JPEG por predefinição. Fontes: Image Generation · Imagine outputs.

Gestão de imagens geradas efémeras

Os URLs devolvidos pela API de geração e edição de imagens são temporários: a documentação da xAI descreve-os como de curta duração sem especificar o seu tempo de vida, e solicita que transfira ou processe as imagens sem demora. Esta restrição impacta diretamente a forma como concebe as suas aplicações.

Temp.
URLs de Saída
b64
Alternativa Persistente
+33%
Sobrecarga de Tamanho Base64
30 dias
Armazenamento xAI, ou ilimitado

O problema dos URLs temporários

Quando utiliza response_format="url" (a predefinição), a API devolve um URL efémero. Após um período não especificado, este deixa de servir a imagem.

# URL efémero: transfira sem demora
response = client.images.generate(
    model="grok-imagine-image",
    prompt="A mountain landscape"
)

url = response.data[0].url

Consequência: não pode armazenar estes URLs numa base de dados e reutilizá-los mais tarde. Deve transferir sistematicamente as imagens.

Estratégia 1: Transferência imediata

A estratégia mais fiável consiste em transferir cada imagem assim que esta é gerada:

import urllib.request
import os
from datetime import datetime

def generate_and_save(prompt, output_dir="images"):
    """Gera uma imagem e guarda-a imediatamente."""
    os.makedirs(output_dir, exist_ok=True)

    response = client.images.generate(
        model="grok-imagine-image",
        prompt=prompt
    )

    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    filepath = os.path.join(output_dir, f"gen_{timestamp}.jpg")  # JPEG por predefinição

    urllib.request.urlretrieve(response.data[0].url, filepath)
    print(f"Imagem guardada: {filepath}")
    return filepath

Estratégia 2: Utilização de Base64

Ao solicitar a resposta em Base64, recebe diretamente os dados binários da imagem, sem depender de um URL temporário:

import base64

response = client.images.generate(
    model="grok-imagine-image",
    prompt="A mountain landscape",
    response_format="b64_json"
)

# Os dados estão diretamente na resposta
image_bytes = base64.b64decode(response.data[0].b64_json)

with open("mountain.jpg", "wb") as f:  # JPEG por predefinição
    f.write(image_bytes)

Vantagens do Base64

A vantagem do Base64 resume-se a uma palavra: autonomia. A imagem chega diretamente na resposta JSON, sem depender de um URL temporário que possa expirar antes de o seu código a consumir, e sem uma solicitação HTTP adicional para a transferir — menos uma ida e volta à rede significa menos um ponto de falha no seu pipeline.

Desvantagens do Base64

A contrapartida é mecânica: a codificação Base64 incha a resposta JSON em cerca de 33%, o que lhe custa três vezes mais — no tempo de transferência da resposta da API, na memória consumida no cliente para a descodificar e na complexidade se manipular várias imagens de alta resolução na mesma solicitação. Para uma imagem isolada, é negligenciável; para um lote de dez imagens 2k, a diferença torna-se tangível.

Estratégia 3: Armazenamento automático na nuvem

Para aplicações de produção, combine a geração com um carregamento para o seu armazenamento:

import boto3
import urllib.request
import tempfile

def generate_and_upload_s3(prompt, bucket, key):
    """Gera uma imagem e carrega-a diretamente para o S3."""
    response = client.images.generate(
        model="grok-imagine-image",
        prompt=prompt
    )

    # Transferir para um ficheiro temporário
    with tempfile.NamedTemporaryFile(suffix=".jpg", delete=False) as tmp:
        urllib.request.urlretrieve(response.data[0].url, tmp.name)

        # Carregar para o S3
        s3 = boto3.client("s3")
        s3.upload_file(tmp.name, bucket, key)

    permanent_url = f"https://{bucket}.s3.amazonaws.com/{key}"
    return permanent_url

Estratégia 4: Deixar a xAI armazenar a imagem

Cada solicitação Imagine aceita um parâmetro storage_options que guarda a imagem produzida na API de Ficheiros da sua equipa e pode, adicionalmente, criar um URL público permanente, para partilha ou incorporação. Com o SDK da xAI:

import os
import xai_sdk

client_xai = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

response = client_xai.image.sample(
    prompt="A mountain landscape at sunrise",
    model="grok-imagine-image-2.0",
    storage_options={"filename": "mountain.jpg", "public_url": True},
)

print(response.file_output.file_id)  # identificador estável na API de Ficheiros
print(response.public_url)           # URL público permanente

A resposta mantém o URL efémero habitual e adiciona, para cada imagem, um bloco file_output: file_id, filename e, se solicitado, public_url. Apenas o filename é obrigatório: sem outras opções, a imagem é armazenada privadamente, sem expiração nem URL público. O parâmetro expires_after (de 3.600 segundos a 30 dias) agenda a eliminação do ficheiro, e o public_url também aceita o seu próprio expires_after, que não pode exceder o do ficheiro. Uma equipa pode ter até 1.000 URLs públicos ativos; além desse limite, ou em caso de incidente, a imagem continua armazenada e a resposta transporta um public_url_error em vez do URL. Via REST, o mesmo objeto storage_options vai no corpo da solicitação, inclusive para uma edição.

Pipeline robusto com repetição

Os URLs temporários podem, por vezes, falhar durante a transferência. Implemente um mecanismo de repetição:

import time
import urllib.request
import urllib.error

def download_with_retry(url, filepath, max_retries=3):
    """Transfere uma imagem com repetição em caso de erro."""
    for attempt in range(max_retries):
        try:
            urllib.request.urlretrieve(url, filepath)
            return True
        except urllib.error.URLError as e:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt  # Backoff exponencial
                print(f"Tentativa {attempt + 1} falhou, a tentar novamente em {wait_time}s...")
                time.sleep(wait_time)
            else:
                print(f"Falhou após {max_retries} tentativas: {e}")
                return False

Boas práticas

Toda a disciplina deriva de um único facto: os URLs são temporários. A transferência deve, portanto, seguir imediatamente a geração, no mesmo fluxo de código — cada minuto de intervalo é uma janela onde a imagem se pode tornar irrecuperável. Pela mesma razão, um URL temporário nunca deve ser armazenado numa base de dados como referência permanente: estará morto na próxima consulta, e este é o tipo de erro que só aparece em produção, dias depois. Em aplicações críticas onde a fiabilidade vem em primeiro lugar, contorne o problema com b64_json, que entrega a imagem na resposta, ou com storage_options, que a mantém na xAI com um identificador estável.

A própria transferência merece ser tratada como uma operação de rede normal: uma repetição com backoff para absorver falhas transitórias, nomeação de ficheiros por carimbo de data/hora ou identificador único para evitar colisões quando várias gerações correm em paralelo. Por fim, registe os metadados — prompt, modelo, parâmetros — com cada imagem guardada: daqui a seis meses, quando precisar de regenerar um visual “como aquele, mas em 2k”, este registo será invaluable.

Pontos-chave

  • Os URLs de saída são temporários: transfira imediatamente
  • O formato b64_json evita o problema do URL efémero
  • O Base64 aumenta o tamanho da resposta em ~33%
  • Implemente uma repetição com backoff exponencial para robustez
  • Em produção, carregue para armazenamento permanente (S3, GCS) ou deixe a xAI armazenar a imagem com storage_options