Gerar Imagem

Propósito

Gera imagens de IA baseadas em prompts de texto. Opcionalmente, você pode fazer upload de imagens de referência para guiar o estilo ou composição do resultado gerado.

Método e Caminho

POST /public/v1/generate/image

Autenticação

Consulte a página de Autenticação. É necessário um token Bearer.

Cabeçalhos Obrigatórios:

Authorization: Bearer {your_api_key}

Campos da Requisição

Nome do Campo	Tipo	Obrigatório	Descrição
prompt	string	Sim	Prompt de texto para geração de imagem
ai_model	string	Sim	Modelo de IA a ser usado. Valores possíveis: GPT Image 1.5, GPT Image 2, Grok Imagine, Grok Imagine Pro, Nano Banana, Nano Banana 2, Nano Banana Pro
ref_images	file[]	Não	Arquivos de imagens de referência (multipart/form-data). O número máximo de uploads varia conforme o modelo de IA

Resposta

Resposta de Sucesso (200 OK):

{
  "job_id": "uuid-string"
}

Campo	Tipo	Descrição
job_id	string	Identificador único do job criado. Consulte o resultado em Get Job Status

Regras de Erro / Validação

Situação	Status HTTP	Mensagem de Erro
Invalid image file	400	"Invalid image file"
Excede 5 ref_images no modelo Grok Imagine	400	"The Grok Imagine model supports up to 5 ref_images."
Excede 1 ref_images no modelo Grok Imagine Pro	400	"The Grok Imagine Pro model supports up to 1 ref_images."
Excede 10 ref_images em outros modelos	400	"ref_images supports up to 10 images only"
Falha de autenticação	401	Chave de API inválida

Limites de Imagens de Referência:

• GPT Image 1.5: máximo 10
• Grok Imagine: máximo 5
• Grok Imagine Pro: máximo 1
• Família Nano Banana: máximo 10

Comportamento do Job Assíncrono

Este endpoint cria um job assíncrono. Ele retorna imediatamente um job_id, e a geração real da imagem ocorre em segundo plano.

Método de Polling:

1. Salve o job_id recebido na resposta
2. Faça polling em GET /public/v1/job/{job_id} para verificar o status
3. Quando o status for Succeed, verifique o resultado em image_urls

Fluxo de Status: Pending → Succeed ou Failed

Exemplo de Requisição

cURL (sem imagens de referência):

curl -X POST "https://api.aetherforgeai.com/public/v1/generate/image" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "prompt=a beautiful sunset over mountains" \
-F "ai_model=GPT Image 1.5"

cURL (com imagens de referência):

curl -X POST "https://api.aetherforgeai.com/public/v1/generate/image" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "prompt=a cat in the style of the reference" \
-F "ai_model=Grok Imagine" \
-F "ref_images=@/path/to/ref1.jpg" \
-F "ref_images=@/path/to/ref2.jpg"