
Este guia da Ideogram 4.6 API leva você de uma chave de API a uma imagem pronta em cURL e Python e depois cobre todos os modos de entrada que o schema da PoYo aceita: text-to-image em tamanhos preset ou personalizados, fundos transparentes, edições regulares, edições com máscara, imagens de referência e edições de alta precisão. Text-to-image usa o ID de modelo ideogram-v4.6 e a edição usa ideogram-v4.6-edit; os dois estão listados na página do modelo Ideogram 4.6.
As regras dos campos vêm da referência da API da PoYo. Para saber o que é o modelo e como ele se compara, comece pela visão geral da Ideogram 4.6 API.
Passo 1: envie uma requisição à Ideogram 4.6 API com cURL
Crie uma chave no painel da PoYo e exporte-a como POYO_API_KEY. Mantenha-a no seu servidor, não no código do navegador.
curl https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "ideogram-v4.6",
"input": {
"prompt": "A colorful storefront with a neon sign reading \"HELLO\""
}
}'
Isso usa os padrões: size: auto (cerca de 2K), quality: medium, uma imagem, então custa 12 créditos ($0.06). Um envio bem-sucedido retorna code: 200 e um objeto data com task_id, status: "not_started" e created_time. Isso é uma tarefa na fila, não uma imagem. Verifique code no corpo sempre: alguns erros de validação voltam com HTTP 200 e code: 400.
Passo 2: consulte o status da tarefa
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
O status passa por not_started, running e depois finished ou failed. Uma tarefa concluída lista uma entrada por imagem em data.files, cada uma com file_url e file_type: "image", e informa o valor cobrado em credits_amount. Uma tarefa que falhou explica o motivo em error_message.
Passo 3: um loop de polling em Python com limite de tempo
Este loop verifica tanto o status HTTP quanto o code do corpo, para em failed, retorna todas as imagens quando n é maior que 1 e desiste após 10 minutos sem reenviar.
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
body = response.json()
if response.status_code >= 400 or body.get("code") != 200:
error = body.get("error") or {}
raise RuntimeError(f"PoYo error {body.get('code')}: {error.get('message', body)}")
return body["data"]
def run(model, input_body, max_wait=600):
task = checked(session.post(BASE + "/api/generate/submit",
json={"model": model, "input": input_body},
timeout=60))
task_id = task["task_id"]
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
time.sleep(5)
task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
if task["status"] == "failed":
raise RuntimeError(task.get("error_message") or "generation failed")
if task["status"] == "finished":
images = [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "image"]
return images, task.get("credits_amount")
raise TimeoutError("Still running, check this task later: " + task_id)
images, credits = run("ideogram-v4.6", {
"prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
"size": "1728x2304",
"quality": "high",
"n": 2,
})
print(images, credits)
1728x2304 é um tamanho 3:4 de 3,981,312 pixels, abaixo da linha de 4,194,304 pixels, então as duas imagens são cobradas pela tarifa 2K high: 2 × 20 = 40 créditos ($0.20). Um timeout significa "consulte o mesmo ID de tarefa mais tarde". Reenviar iniciaria uma segunda tarefa cobrável. A mesma run() funciona para edições: passe "ideogram-v4.6-edit" como modelo.
Todos os modos de entrada da Ideogram 4.6 API
Todos os campos vão dentro de input. O ID de modelo e um callback_url opcional ficam no nível superior.
Text-to-image em 4K
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
"size": "2048x3072",
"quality": "high",
"n": 2
}
}
2048x3072 tem 6,291,456 pixels, acima de 4,194,304, então esta é a faixa 4K e very_low não é permitido nesse tamanho.
Fundo transparente e seed fixa
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A flat sticker of a smiling coffee cup",
"size": "1:1 HD",
"quality": "low",
"background": "transparent",
"seed": 42
}
}
transparent retorna uma imagem com canal alfa; opaque força um fundo sólido. Envie o mesmo corpo com a mesma seed para repetir um resultado.
Edição regular
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Replace the background with a blue photo studio",
"image_urls": [
"https://example.com/source.png"
]
}
}
Uma edição regular regenera a imagem a partir do prompt. image_urls deve ser um array com exatamente uma imagem, como URL HTTP(S) pública ou data URI em base64. Para enviar arquivos locais, faça o upload antes com o endpoint de upload de arquivos da PoYo.
Mudança de estilo com uma imagem de referência
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Restyle the product shot to match the reference",
"image_urls": [
"https://example.com/product.png"
],
"reference_image_urls": [
"https://example.com/style.png"
],
"size": "2048x2048",
"quality": "low",
"n": 2
}
}
São permitidas até 4 referências, ou 3 com máscara. Um size personalizado é permitido aqui porque esta é uma edição regular sem máscara.
Edição de alta precisão da imagem inteira
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Change only the date line to \"JULY 3-5 · RIVERSIDE PARK\". Keep everything else exactly the same.",
"image_urls": [
"https://example.com/poster.png"
],
"edit_precision": "high",
"context_window": "none",
"size": "auto",
"quality": "high"
}
}
Este é o corpo da nossa edição do dia do lançamento (tarefa 672JRU198S22NS8D, 20 de novembro de 2026), com a URL de origem substituída. A origem era um pôster de 2304×3072; a saída manteve esse tamanho e alterou apenas a linha da data, e a tarefa foi cobrada em 120 créditos ($0.60), a tarifa de edição 4K high.
Edição localizada com máscara
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Change the sign text to \"OPEN LATE\"",
"image_urls": [
"https://example.com/storefront.png"
],
"mask_url": "https://example.com/sign-mask.png",
"edit_precision": "high",
"context_window": "auto",
"quality": "high"
}
}
A máscara deve ter as mesmas dimensões da origem e conter áreas pretas (editar) e brancas (manter). Com context_window: auto, só a região em volta da máscara é editada, na resolução da origem. Uma máscara grande demais volta à edição da imagem inteira.
Regras de validação dos campos
Valide do seu lado antes de enviar, para que requisições ruins falhem rápido:
| Campo | Regra |
|---|---|
model | ideogram-v4.6 ou ideogram-v4.6-edit |
prompt | Obrigatório, de 1 a 10,000 caracteres, não só espaços em branco |
size | auto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 ou WIDTHxHEIGHT com x minúsculo |
| Tamanho personalizado | Cada lado entre 256 e 4096 e múltiplo de 32; proporção entre 1:6 e 6:1 |
quality | very_low só quando a saída tem no máximo 4,194,304 pixels |
n | Inteiro de 1 a 8; strings e booleanos são rejeitados |
image_urls | Só em edição; array com exatamente uma imagem |
mask_url, edit_precision: high | Exigem size: auto (ou nenhum size) |
background | Rejeitado quando edit_precision é high |
context_window: auto | Exige mask_url e edit_precision: high |
| Campos desconhecidos | Rejeitados com um erro unsupported fields |
Exemplos: 2304x3072 passa (os dois lados são múltiplos de 32); 1296x3168 falha porque 1296 não é múltiplo de 32, mesmo que o Ideogram 4.5 o aceitasse; 4096x512 falha (proporção 8:1); very_low em 2048x3072 falha.
Erros que vale a pena tratar
code | Significado | O que fazer |
|---|---|---|
| 400 | Parâmetros inválidos | Corrija o corpo; não repita sem alterações |
| 401 | Chave de API ausente ou inválida | Verifique o header Authorization: Bearer |
| 402 | Créditos insuficientes | Recarregue e reenvie |
| 429 | Limite de requisições excedido | Espere e tente de novo mais tarde |
| 500, 502, 503 | Erro do servidor, do upstream ou de disponibilidade | Tente de novo com backoff; antes, verifique se um ID de tarefa já foi retornado |
Uma tarefa que chega a failed traz o motivo em error_message. Veja Error Codes para a lista completa.
Use um callback em vez de polling
Adicione "callback_url": "https://your-app.example.com/poyo-webhook" no nível superior do corpo, não dentro de input. Quando a tarefa termina ou falha, a PoYo faz um POST com os dados da tarefa para essa URL, assinado com HMAC-SHA256 no header X-Webhook-Signature; a documentação de webhooks traz a regra da assinatura. Mantenha um polling lento como fallback para callbacks que nunca chegam.
Como sua primeira cobrança é calculada
A Ideogram 4.6 API cobra por imagem de saída: preço da faixa de qualidade e tamanho × n. 1 crédito = $0.005.
| Requisição | Faixa | Cobrança |
|---|---|---|
Padrões (auto, medium, n: 1) | Text-to-image medium 2K | 12 créditos ($0.06) |
very_low, 3:4, n: 1 | Text-to-image very_low 2K | 1.6 créditos ($0.008) |
high, 1728x2304, n: 2 | Text-to-image high 2K | 40 créditos ($0.20) |
high, 2304x3072, n: 1 | Text-to-image high 4K | 40 créditos ($0.20) |
Edição de alta precisão de uma origem de 2304×3072, high | Edição high 4K | 120 créditos ($0.60) |
As linhas very_low e 2304x3072 correspondem ao que foi cobrado nas nossas tarefas do dia do lançamento. Em edições com size: auto, o preço é cotado pelo tamanho da imagem de origem e liquidado pela imagem entregue, nunca acima da cotação. O post de preços tem mais exemplos calculados.
Perguntas frequentes
A Ideogram 4.6 API é compatível com o SDK da OpenAI?
Não. É uma API de tarefas assíncronas: envie para /api/generate/submit e depois consulte /api/generate/status/{task_id} ou receba um callback. requests, fetch ou cURL puros funcionam.
Como edito uma imagem com a Ideogram 4.6 API?
Chame ideogram-v4.6-edit com uma URL em image_urls e a alteração em prompt. Adicione edit_precision: high para manter os pixels que você não pediu para alterar.
Posso enviar imagens de referência para ideogram-v4.6?
Não. Na PoYo, as referências vão em reference_image_urls no ideogram-v4.6-edit, até 4, ou 3 com máscara.
Quantas imagens uma requisição à Ideogram 4.6 API retorna?
De 1 a 8, definidas com n. Cada imagem é cobrada pelo preço da faixa.
Por que minha requisição à Ideogram 4.6 API foi rejeitada pelo tamanho?
Os lados personalizados devem ser múltiplos de 32 entre 256 e 4096, e máscaras ou edições de alta precisão exigem size: auto.