how-tos

Ideogram 4.6 API: guia da primeira imagem e edição em cURL e Python

Poyo.ai Team
9 min read
Share:

Guia da Ideogram 4.6 API com cURL e Python

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:

CampoRegra
modelideogram-v4.6 ou ideogram-v4.6-edit
promptObrigatório, de 1 a 10,000 caracteres, não só espaços em branco
sizeauto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 ou WIDTHxHEIGHT com x minúsculo
Tamanho personalizadoCada lado entre 256 e 4096 e múltiplo de 32; proporção entre 1:6 e 6:1
qualityvery_low só quando a saída tem no máximo 4,194,304 pixels
nInteiro de 1 a 8; strings e booleanos são rejeitados
image_urlsSó em edição; array com exatamente uma imagem
mask_url, edit_precision: highExigem size: auto (ou nenhum size)
backgroundRejeitado quando edit_precision é high
context_window: autoExige mask_url e edit_precision: high
Campos desconhecidosRejeitados 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

codeSignificadoO que fazer
400Parâmetros inválidosCorrija o corpo; não repita sem alterações
401Chave de API ausente ou inválidaVerifique o header Authorization: Bearer
402Créditos insuficientesRecarregue e reenvie
429Limite de requisições excedidoEspere e tente de novo mais tarde
500, 502, 503Erro do servidor, do upstream ou de disponibilidadeTente 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çãoFaixaCobrança
Padrões (auto, medium, n: 1)Text-to-image medium 2K12 créditos ($0.06)
very_low, 3:4, n: 1Text-to-image very_low 2K1.6 créditos ($0.008)
high, 1728x2304, n: 2Text-to-image high 2K40 créditos ($0.20)
high, 2304x3072, n: 1Text-to-image high 4K40 créditos ($0.20)
Edição de alta precisão de uma origem de 2304×3072, highEdição high 4K120 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.

Share: