Moderação, incompatibilidades do SDK e controlo de custos
Nesta página
Atualizado a 2 de novembro de 2026 — Imagine. O modelo
grok-imagine-image-qualityfoi removido a 2 de novembro de 2026 (os seus pedidos são agora servidos pelo Imagine 2.0 em qualidadelow): os exemplos atuais utilizamgrok-imagine-image(Imagine 1.0) egrok-imagine-image-2.0(Imagine 2.0, com qualidadelow,mediumouauto). Com o SDK da OpenAI, os parâmetrosaspect_ratio,resolutionequalitydevem ser passados através deextra_body, enquanto a edição de imagens requer o SDK da xAI ou uma solicitação HTTP direta.
Compreenda os limites da API de imagens
Para construir aplicações fiáveis com a API de geração de imagens do Grok, precisa de conhecer os seus limites: moderação automática, incompatibilidade com certos métodos do SDK da OpenAI e mecanismos de controlo de custos.
Moderação de conteúdos
A API modera automaticamente os prompts e as imagens geradas. Determinados tipos de conteúdo são recusados:
- Conteúdos explicitamente violentos ou sangrentos
- Conteúdos explicitamente sexuais
- Conteúdos de ódio ou discriminatórios
- Conteúdos que envolvam menores de forma inadequada
Quando a moderação é acionada, a API devolve um erro em vez de uma imagem.
Trate as recusas por moderação
import requests
import os
headers = {
"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
"Content-Type": "application/json"
}
def generate_safe(prompt, **kwargs):
"""Gera uma imagem tratando as recusas por moderação."""
try:
response = requests.post(
"https://api.x.ai/v1/images/generations",
headers=headers,
json={"model": "grok-imagine-image", "prompt": prompt, **kwargs}
)
response.raise_for_status()
return response.json()["data"][0]["url"]
except requests.exceptions.HTTPError as e:
if response.status_code == 400:
print(f"Prompt recusado pela moderação: {prompt[:50]}...")
return None
raise
Boas práticas de moderação
Na prática, deve tratar a moderação a montante, em vez de reagir apenas após o erro. Se um prompt legítimo for bloqueado, teste variações para identificar a palavra-gatilho — “batalha épica” passará onde um termo mais grosseiro não passará; mapear estas sensibilidades evita bloqueios recorrentes. Quando os prompts vêm dos seus utilizadores, adicione um pré-filtro no servidor antes da chamada à API: isto intercepta pedidos obviamente fora das políticas sem consumir uma solicitação e mantém-no no controlo da mensagem exibida. Porque é este último ponto que faz a diferença na experiência: um bloqueio por moderação nunca deve chegar ao utilizador como um erro técnico bruto, mas sim como uma mensagem clara — “este pedido não cumpre os nossos termos de utilização” — que explica sem expor detalhes da API.
Incompatibilidade do SDK da OpenAI para edição
Este é um ponto crítico: o método images.edit() do SDK da OpenAI não funciona com a API da xAI. O SDK da OpenAI envia os dados como multipart/form-data, enquanto a API da xAI espera application/json.
# NÃO FUNCIONA
from openai import OpenAI
client = OpenAI(api_key=os.getenv("XAI_API_KEY"), base_url="https://api.x.ai/v1")
client.images.edit(
model="grok-imagine-image",
image=open("photo.png", "rb"),
prompt="Edit this image"
)
# → Erro de Content-type!
# FUNCIONA: chamada REST direta
import requests
response = requests.post(
"https://api.x.ai/v1/images/edits",
headers={
"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
"Content-Type": "application/json"
},
json={
"model": "grok-imagine-image",
"prompt": "Edit this image",
"image": {"url": "https://exemple.com/photo.jpg"}
}
)
Resumo de compatibilidade
| Operação | SDK da OpenAI | REST (requests) |
|---|---|---|
| images.generate() | Compatível | Compatível |
| images.edit() | Incompatível | Compatível |
Controlo de custos
Monitore o consumo
Configure um contador de gastos no seu código:
class ImageBudgetTracker:
PRICES = {
"grok-imagine-image": 0.02,
"grok-imagine-image-2.0": 0.04, # qualidade low; medium à taxa da grelha
}
def __init__(self, budget_limit=10.0):
self.total_spent = 0.0
self.budget_limit = budget_limit
self.image_count = 0
def can_generate(self, model, n=1):
cost = self.PRICES[model] * n
return (self.total_spent + cost) <= self.budget_limit
def record(self, model, n=1):
cost = self.PRICES[model] * n
self.total_spent += cost
self.image_count += n
def report(self):
remaining = self.budget_limit - self.total_spent
print(f"Images generated: {self.image_count}")
print(f"Spent: ${self.total_spent:.2f}")
print(f"Remaining budget: ${remaining:.2f}")
# Utilização
tracker = ImageBudgetTracker(budget_limit=5.0)
if tracker.can_generate("grok-imagine-image", n=5):
response = client.images.generate(
model="grok-imagine-image",
prompt="My image",
n=5
)
tracker.record("grok-imagine-image", n=5)
tracker.report()
Otimize os custos
A regra de ouro é separar a exploração da produção. Durante a pesquisa de prompts, trabalhe com o Imagine 1.0 ($0,02) com n=3-5 para comparar variações a um custo menor; assim que o prompt estiver estável, mude para o Imagine 2.0 com n=1 para a renderização final. Esta sequência reserva a tarifa mais elevada apenas para as imagens selecionadas.
Dois mecanismos completam a configuração do lado da aplicação. Primeiro, uma cache de resultados: se o mesmo prompt retornar — visuais de catálogo, imagens padrão regeneradas por vários utilizadores — sirva a imagem já gerada em vez de pagar por um novo pedido. Depois, as quotas, caso os seus utilizadores acionem as gerações: um limite por dia ou por hora protege o seu orçamento contra usos irracionais e abusos. Por fim, fique atento aos limites de taxa (300 RPM padrão, 30 RPM pro): um pipeline em lote que os ignore acumulará erros 429 e novas tentativas desnecessárias.
Estimativa de orçamento mensal
Para uma aplicação com 100 utilizadores a gerar 10 imagens por dia:
- Imagine 1.0: 100 x 10 x 30 x $0,02 = $600/mês
- Imagine 2.0 em
low: 100 x 10 x 30 x $0,04 = $1.200/mês - Misto (80/20): 24.000 x $0,02 + 6.000 x $0,04 = $720/mês
Endpoint de descoberta de modelos
Para verificar programaticamente os modelos de imagem disponíveis e os seus preços:
response = requests.get(
"https://api.x.ai/v1/image-generation-models",
headers={"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}"}
)
for model in response.json()["data"]:
print(f"{model['id']} : ${model['image_price']}/image, "
f"max prompt : {model['max_prompt_length']} chars")
Tarifas a partir de 5 de agosto de 2026 — os preços mudam regularmente: antes de qualquer cálculo de orçamento, verifique a grelha atual na página oficial de modelos e tarifas da xAI.
Pontos-chave
- A moderação é automática: trate as recusas no seu código
- O
images.edit()do SDK da OpenAI é incompatível com a xAI: utilizerequests - O
images.generate()do SDK da OpenAI funciona normalmente - Implemente um rastreador de orçamento para controlar os gastos
- Verifique os modelos e preços através do endpoint
/v1/image-generation-models
Teste os seus conhecimentos
Geração e edição de imagens: a visão geral operacional.
1. O que diferencia o Imagine 1.0 do Imagine 2.0?
Resposta: A relação qualidade/custo: o Imagine 1.0 ($0,02) para volume e iterações, o Imagine 2.0 ($0,04 em low, com definição de quality) para renderizações finais — faz o protótipo com o primeiro e finaliza com o segundo.
2. O que constitui um bom prompt de imagem?
Resposta: Assunto, estilo, composição e detalhes explícitos — descreva a cena como um briefing de direção de arte e itere com ajustes direcionados em vez de reescrever tudo.
3. O que permite o endpoint /v1/images/edits?
Resposta: Editar imagens existentes: edição direcionada por prompt, edição de múltiplas imagens com referências e edição em múltiplos turnos — retoca com precisão em vez de regenerar.
4. Como produzir em volume com eficiência?
Resposta: O parâmetro n para lotes, o cliente assíncrono para throughput — e como os URLs de saída são temporários, faça o download e arquive imediatamente.
5. Que salvaguardas implementar antes da produção?
Resposta: Moderação de prompts e resultados, conhecimento das incompatibilidades do SDK e controlo de custos (modelo, resolução, volumes) — a criação em escala exige governança.
Prototipe, edite, industrialize, governe: o pipeline completo de imagens — com custos sob controlo em cada etapa.