Imagens e Vídeos em Lotes
Nesta página
Atualizado em 2 de novembro de 2026 com base na documentação da xAI: o desconto para lotes é de 20% em modelos de texto elegíveis (não 50%), os exemplos seguem a API REST e o
xai-sdkoficial (client.batch.*; a API de Lotes da xAI não utiliza o formato OpenAI, pelo que o SDK da OpenAI não se aplica), e a API de Respostas tem precedência sobre as Conclusões de Chat, um endpoint legado na xAI. Fontes: API de Lotes · Referência REST · Preços de Lotes.
Geração Multimodal em Massa
A API de Lotes não se limita ao texto. Pode submeter gerações e edições de imagens, bem como gerações, edições e extensões de vídeo. Esta capacidade abre portas para pipelines multimodais completos: escrever descrições e produzir os seus visuais numa única operação.
Geração de Imagens em Lote
O endpoint /v1/images/generations funciona em lote tal como no modo síncrono. Selecione o formato com aspect_ratio, a definição com resolution ("1k", "1.5k" ou "2k") e o número de imagens com n:
{"custom_id": "img-001", "method": "POST", "url": "/v1/images/generations", "body": {"model": "grok-imagine-image-2.0", "prompt": "Minimalist logo for a fintech startup, white background, vector style", "n": 1, "aspect_ratio": "1:1", "resolution": "1k"}}
{"custom_id": "img-002", "method": "POST", "url": "/v1/images/generations", "body": {"model": "grok-imagine-image-2.0", "prompt": "Isometric illustration of a datacenter", "n": 1, "aspect_ratio": "16:9", "resolution": "1k"}}
Edição de Imagens em Lote
O endpoint /v1/images/edits modifica uma imagem existente, passada num objeto image: um url (endereço público ou dados codificados em base64) ou o file_id de um ficheiro carregado.
{"custom_id": "edit-001", "method": "POST", "url": "/v1/images/edits", "body": {"model": "grok-imagine-image-2.0", "prompt": "Replace the background with a solid white background", "image": {"url": "https://example.com/photo.jpg"}}}
No modo de lote, a edição ajuda a processar um catálogo: harmonizar fundos, adicionar um elemento ou aplicar o mesmo retoque a centenas de visuais.
Geração de Vídeos em Lote
O endpoint /v1/videos/generations (ou /v1/videos) gera vídeos de 1 a 15 segundos (duration, 8 por predefinição), em 480p, 720p ou 1080p:
{"custom_id": "vid-001", "method": "POST", "url": "/v1/videos/generations", "body": {"model": "grok-imagine-video-1.5", "prompt": "Smooth animation of a bar chart growing progressively", "duration": 8, "resolution": "720p"}}
O processamento de vídeo é mais pesado do que o de texto ou imagens, pelo que estes pedidos podem demorar mais tempo dentro do lote.
Edição e Extensão de Vídeo
O endpoint /v1/videos/edits modifica um vídeo existente, e o /v1/videos/extensions estende-o com um segmento de 2 a 10 segundos. Passe o vídeo de origem num objeto video (URL de um ficheiro .mp4 ou file_id):
{"custom_id": "vid-edit-001", "method": "POST", "url": "/v1/videos/edits", "body": {"model": "grok-imagine-video", "prompt": "Slow down the scene", "video": {"url": "https://example.com/clip.mp4"}}}
{"custom_id": "vid-ext-001", "method": "POST", "url": "/v1/videos/extensions", "body": {"model": "grok-imagine-video", "prompt": "The camera slowly pulls back and reveals a sunset", "video": {"url": "https://example.com/clip.mp4"}, "duration": 6}}
Utilização do SDK Python
O SDK prepara estes pedidos com métodos dedicados e adiciona-os ao lote tal como os pedidos de texto:
from xai_sdk import Client
client = Client()
batch = client.batch.create(batch_name="catalog_visuals")
requetes = [
client.image.prepare(
prompt="Product shot of wireless headphones, dark background, studio lighting",
model="grok-imagine-image-2.0",
batch_request_id="prod-42-img",
),
client.video.prepare(
prompt="The headphones rotate slowly on a turntable, dramatic lighting",
model="grok-imagine-video-1.5",
batch_request_id="prod-42-vid",
),
]
client.batch.add(batch_id=batch.batch_id, batch_requests=requetes)
Preços de Conteúdo Multimodal
Ponto importante: o desconto de lote aplica-se apenas a modelos de texto elegíveis. Imagens e vídeos são faturados à tarifa padrão, mesmo no modo de lote — a partir de 2 de novembro de 2026, $0,04 por imagem com grok-imagine-image-2.0 ($0,02 com grok-imagine-image) e $0,08 por segundo de vídeo com grok-imagine-video-1.5 ($0,02 na versão -lite, $0,05 com grok-imagine-video).
A vantagem dos lotes para conteúdo multimodal não é o preço, mas sim operacional: submeta centenas de gerações numa única operação, sem gerir tantas chamadas ou atingir limites de taxa.
Expiração do URL do Resultado
Os resultados de imagens e vídeos são fornecidos como URLs assinados que expiram após uma hora. Esta é uma restrição crítica: descarregue os ficheiros assim que recuperar os resultados.
import mimetypes
import requests
def telecharger_medias(resultats, dossier):
"""Downloads images and videos as soon as results are retrieved."""
for r in resultats:
reponse = r.proto.response
if reponse.HasField("image_response"):
url = r.image_response.url
elif reponse.HasField("video_response"):
url = r.video_response.url
else:
continue # text result
fichier = requests.get(url, timeout=120)
fichier.raise_for_status()
type_mime = fichier.headers.get("Content-Type", "").split(";")[0]
extension = mimetypes.guess_extension(type_mime) or ".bin"
with open(f"{dossier}/{r.batch_request_id}{extension}", "wb") as f:
f.write(fichier.content)
Nunca guarde URLs assinados para utilização posterior: guarde os ficheiros no seu próprio armazenamento (S3, GCS, disco local).
Pipeline Multimodal Misto
Um caso de uso concreto: produzir fichas de produto completas, texto e visual, no mesmo lote:
{"custom_id": "prod-42-desc", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": "Write a marketing description for a high-end wireless headphone.", "max_output_tokens": 300}}
{"custom_id": "prod-42-img", "method": "POST", "url": "/v1/images/generations", "body": {"model": "grok-imagine-image-2.0", "prompt": "Product shot of premium wireless headphones, dark gradient background, studio lighting"}}
Um prefixo comum nos identificadores (prod-42-desc, prod-42-img) facilita o agrupamento dos resultados de texto e imagem para o mesmo produto.
Pontos-chave
- Imagens (geração, edição) e vídeos (geração, edição, extensão) funcionam em lotes
- Os parâmetros correspondem à API:
aspect_ratio,resolution, objetosimageevideo - Imagens e vídeos mantêm-se nas tarifas padrão, sem descontos de lote
- Os URLs de resultados assinados expiram após uma hora: descarregue imediatamente
- Um prefixo comum nos identificadores agrupa resultados para o mesmo produto