
Este guia da Ideogram 4.6 API leva-o de uma API key a uma imagem final em cURL e Python e, depois, cobre todos os modos de entrada que o esquema da PoYo aceita: text-to-image em tamanhos predefinidos ou personalizados, fundos transparentes, edições normais, edições com máscara, imagens de referência e edições de alta precisão. O text-to-image usa o ID de modelo ideogram-v4.6 e a edição usa ideogram-v4.6-edit; ambos constam da 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 se compara, comece pela apresentação da Ideogram 4.6 API.
Passo 1: submeter um pedido à 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 browser.
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\""
}
}'
Isto usa as predefinições: size: auto (cerca de 2K), quality: medium e uma imagem, pelo que custa 12 créditos ($0.06). Uma submissão bem-sucedida devolve code: 200 e um objeto data com task_id, status: "not_started" e created_time. Trata-se de uma tarefa em fila, não de uma imagem. Verifique sempre o code no corpo: alguns erros de validação chegam com HTTP 200 e code: 400.
Passo 2: consultar o estado da tarefa
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
O estado 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 indica o custo em credits_amount. Uma tarefa falhada explica o motivo em error_message.
Passo 3: um ciclo de polling em Python com limite de tempo
Este ciclo verifica tanto o estado HTTP como o code do corpo, para em failed, devolve todas as imagens quando n é superior a 1 e desiste ao fim de 10 minutos sem voltar a submeter.
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 píxeis, abaixo da linha de 4,194,304 píxeis, por isso as duas imagens são faturadas à tarifa 2K de qualidade alta: 2 × 20 = 40 créditos ($0.20). Um timeout significa «volte a consultar o mesmo ID de tarefa mais tarde». Voltar a submeter iniciaria uma segunda tarefa faturável. A mesma função run() serve 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 são 6,291,456 píxeis, acima de 4,194,304, por isso este é o escalão 4K e very_low não é permitido neste tamanho.
Fundo transparente e seed fixo
{
"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 devolve uma imagem com canal alfa; opaque força um fundo sólido. Envie o mesmo corpo com o mesmo seed para repetir um resultado.
Edição normal
{
"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 normal regenera a imagem a partir do prompt. image_urls tem de ser um array com exatamente uma imagem, como URL HTTP(S) público ou data URI em base64. Para enviar ficheiros locais, carregue-os primeiro com o endpoint de carregamento de ficheiros 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. Aqui é permitido um size personalizado porque se trata de uma edição normal 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 o URL de origem substituído. A origem era um cartaz de 2304×3072; a saída manteve esse tamanho e alterou apenas a linha da data, e a tarefa foi cobrada a 120 créditos ($0.60), a tarifa de edição 4K de qualidade alta.
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 tem de corresponder às dimensões da origem e conter áreas pretas (editar) e brancas (manter). Com context_window: auto, só a região à volta da máscara é editada, à resolução da origem. Uma máscara demasiado grande recorre à edição da imagem inteira.
Regras de validação dos campos
Valide do seu lado antes de submeter, para que os pedidos inválidos falhem logo:
| Campo | Regra |
|---|---|
model | ideogram-v4.6 ou ideogram-v4.6-edit |
prompt | Obrigatório, de 1 a 10,000 carateres, não apenas espaços |
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 de 256 a 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 píxeis |
n | Inteiro de 1 a 8; strings e booleanos são rejeitados |
image_urls | Apenas na 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 é aceite (ambos os lados são múltiplos de 32); 1296x3168 falha porque 1296 não é múltiplo de 32, embora 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 | API key em falta ou inválida | Verifique o cabeçalho Authorization: Bearer |
| 402 | Créditos insuficientes | Carregue créditos e volte a submeter |
| 429 | Limite de pedidos excedido | Aguarde e tente novamente mais tarde |
| 500, 502, 503 | Erro do servidor, do fornecedor ou de disponibilidade | Repita com backoff; verifique primeiro se já foi devolvido um ID de tarefa |
Uma tarefa que chega a failed indica o motivo em error_message. Consulte os códigos de erro para a lista completa.
Usar 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 envia por POST os dados da tarefa para esse URL, assinados com HMAC-SHA256 no cabeçalho X-Webhook-Signature; a documentação de webhooks explica a regra da assinatura. Mantenha um polling lento de reserva para os callbacks que nunca chegam.
Como é calculada a sua primeira fatura
A Ideogram 4.6 API fatura por imagem de saída: preço do escalão de qualidade e tamanho × n. 1 crédito = $0.005.
| Pedido | Escalão | Custo |
|---|---|---|
Predefiniçõ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 de very_low e 2304x3072 coincidem com o que foi cobrado nas nossas tarefas do dia do lançamento. Nas edições com size: auto, o preço é orçamentado a partir do tamanho da imagem de origem e liquidado sobre a imagem entregue, nunca acima do orçamento. O artigo de preços tem mais exemplos práticos.
Perguntas frequentes
A Ideogram 4.6 API é compatível com o SDK da OpenAI?
Não. É uma API de tarefas assíncronas: submeta para /api/generate/submit e depois consulte /api/generate/status/{task_id} ou receba um callback. Basta requests, fetch ou cURL.
Como edito uma imagem com a Ideogram 4.6 API?
Chame ideogram-v4.6-edit com um URL em image_urls e a alteração em prompt. Adicione edit_precision: high para manter os píxeis que 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 devolve um pedido à Ideogram 4.6 API?
De 1 a 8, definido com n. Cada imagem é faturada ao preço do seu escalão.
Porque é que a Ideogram 4.6 API rejeitou o meu pedido por causa do tamanho?
Os lados personalizados têm de ser múltiplos de 32 entre 256 e 4096, e as máscaras ou edições de alta precisão exigem size: auto.