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

Moderação, incompatibilidades do SDK e controlo de custos

Aula 14 de 14 Atualizada a 3 de novembro de 2026 Iniciante
Nesta página
  1. Compreenda os limites da API de imagens
  2. Moderação de conteúdos
  3. Incompatibilidade do SDK da OpenAI para edição
  4. Controlo de custos
  5. Endpoint de descoberta de modelos
  6. Pontos-chave
  7. Teste os seus conhecimentos

Atualizado a 2 de novembro de 2026 — Imagine. O modelo grok-imagine-image-quality foi removido a 2 de novembro de 2026 (os seus pedidos são agora servidos pelo Imagine 2.0 em qualidade low): os exemplos atuais utilizam grok-imagine-image (Imagine 1.0) e grok-imagine-image-2.0 (Imagine 2.0, com qualidade low, medium ou auto). Com o SDK da OpenAI, os parâmetros aspect_ratio, resolution e quality devem ser passados através de extra_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: utilize requests
  • 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.