how-tos

Ideogram 4.6 API: guia para a 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-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:

CampoRegra
modelideogram-v4.6 ou ideogram-v4.6-edit
promptObrigatório, de 1 a 10,000 carateres, não apenas espaços
sizeauto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 ou WIDTHxHEIGHT com x minúsculo
Tamanho personalizadoCada lado de 256 a 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 píxeis
nInteiro de 1 a 8; strings e booleanos são rejeitados
image_urlsApenas na 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 é 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

codeSignificadoO que fazer
400Parâmetros inválidosCorrija o corpo; não repita sem alterações
401API key em falta ou inválidaVerifique o cabeçalho Authorization: Bearer
402Créditos insuficientesCarregue créditos e volte a submeter
429Limite de pedidos excedidoAguarde e tente novamente mais tarde
500, 502, 503Erro do servidor, do fornecedor ou de disponibilidadeRepita 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.

PedidoEscalãoCusto
Predefiniçõ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 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.

Share: