Integração da API de texto para imagem do Seedream 5.0 Pro: curl, Python e técnicas para escrever texto

O texto para imagem do Seedream 5.0 Pro (seedream-5.0-pro/text-to-image) é a opção mais cara da família Seedream 5.0, e seu ponto forte é o texto na imagem: letreiros, embalagens e títulos de pôsteres escritos literalmente conforme o prompt. Este artigo traz exemplos de curl e Python prontos para rodar, todos os parâmetros, erros comuns e algumas técnicas para fazer o texto sair correto.

Preços primeiro

Resolução	Por imagem	100 imagens
1K	$0,05	$5
2K (padrão)	$0,10	$10

Preço atual da HiAPI, verificado em 18 de outubro de 2026.

A proporção não afeta o preço, e falhas não são cobradas. O Pro não tem 4K; para 4K, use o Seedream 5.0 Lite (2K/4K com o mesmo preço de $0,035). Veja a comparação das três opções em Preços da API Seedream 5.0.

Uma imagem real gerada

16:9, 1K, com o texto do letreiro neon escrito literalmente:

A neon-lit night market street in a rainy cyberpunk city, a glowing storefront sign reads "SEEDREAM 5 PRO" in crisp lettering, cinematic composition, dramatic directional lighting, rich cohesive color grade, ultra-detailed, premium commercial finish, subtle film grain, shallow depth of field, high dynamic range

Gerar com este prompt →

seedream-5.0-pro/text-to-image, 16:9, 1K, $0,05.

Gerando a primeira imagem

Preparação: crie uma API Key no console e defina-a como variável de ambiente:

export HIAPI_KEY="sua Key"

curl: enviar a tarefa

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro/text-to-image",
    "input": {
      "prompt": "A cozy coffee shop storefront at dusk, warm window light, a hand-painted wooden sign that reads \"THE DAILY GRIND\" in serif letters",
      "aspect_ratio": "16:9",
      "resolution": "2K"
    }
  }'

Retorna o taskId:

{"code": 200, "message": "success", "data": {"taskId": "tk-hiapi-..."}}

curl: consultar o resultado

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-..." \
  -H "Authorization: Bearer $HIAPI_KEY"

Quando data.status for success, o endereço da imagem estará em data.output[0].url. É um link temporário com expiração; baixe assim que receber:

curl -o result.png "<url em output>"

Em 2K, a imagem costuma sair em cerca de um minuto.

Python (somente biblioteca padrão)

import json, os, time, urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = os.environ["HIAPI_KEY"]

def api(url, payload=None):
    req = urllib.request.Request(
        url,
        data=json.dumps(payload).encode() if payload else None,
        headers={"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"},
        method="POST" if payload else "GET",
    )
    with urllib.request.urlopen(req) as resp:
        return json.loads(resp.read())

task_id = api(API, {
    "model": "seedream-5.0-pro/text-to-image",
    "input": {
        "prompt": 'A minimalist product poster on matte black, bold white headline that reads "SHIP FASTER", small caption "batch v2.1" bottom right',
        "aspect_ratio": "3:4",
        "resolution": "2K",
    },
})["data"]["taskId"]

while True:
    task = api(f"{API}/{task_id}")["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        raise RuntimeError(task)
    time.sleep(5)

urllib.request.urlretrieve(task["output"][0]["url"], "result.png")

Todos os parâmetros

Campo	Obrigatório	Valores
prompt	Sim	3–4000 caracteres, recomenda-se manter em cerca de 600 palavras em inglês ou menos
aspect_ratio	Sim	1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9
resolution	Sim	1K ($0,05) ou 2K ($0,10)
output_format	Não	png (padrão) ou jpeg

Os campos são rigorosos: seed, n, size, image_urls não são aceitos, e enviar campos extras retorna HTTP 400. Cada requisição gera uma imagem; para várias imagens, envie várias tarefas em paralelo.

As resoluções variam entre as opções da mesma família: o Pro é 1K/2K, o Lite é 2K/4K. Ao mudar de opção, lembre-se de alterar o resolution.

Fazendo o texto sair correto

• Coloque o texto entre aspas: a sign that reads "OPEN 24 HOURS" é muito mais confiável do que parafrasear.
• Especifique posição e estilo: sensação da fonte (serifada, manuscrita, neon), posição (canto inferior direito, centralizado), suporte (placa de madeira, porta de vidro).
• Não exagere no texto: alguns trechos curtos por imagem funcionam bem; blocos longos de texto são instáveis.
• Se o texto for o foco, use 2K: letras pequenas ficam mais nítidas em alta resolução.

Erros comuns

Sintoma	Retorno	Como corrigir
Campo obrigatório ausente	400, missing required field "aspect_ratio"	Envie os três campos obrigatórios
Valor de enum inválido	400, resolution: value must be one of '1K', '2K'	Preencha conforme a tabela acima
Envio de seed, n etc.	400, additional properties ... not allowed	Remova os campos extras
Key inválida	401, permission_denied	Verifique a Key no console

Se a tarefa falhar após ser criada, o resultado da consulta terá status: "fail" e não haverá cobrança.

Antes de ir para produção

• Use callback em vez de polling: no nível superior do corpo da requisição (no mesmo nível de model e input), adicione "callback": {"url": "https://seu-dominio/hooks/hiapi", "when": "final"}. Ao receber a notificação, faça um GET da tarefa para confirmar o resultado.
• Evite cobrança duplicada: a cobrança ocorre assim que a tarefa é aceita. Antes de tentar novamente, verifique se você registrou o taskId dessa tarefa; se sim, continue consultando, não reenvie; você também pode enviar o cabeçalho Idempotency-Key na requisição.
• Salve o arquivo a tempo: o link de saída expira, não o use diretamente como link externo.

Perguntas frequentes

É possível fixar o seed para reproduzir?

Não, esta interface não aceita seed. Para gerar versões semelhantes a partir de uma imagem existente, use seedream-5.0-pro/image-to-image, com até 10 imagens de referência.

Qual a diferença em relação ao Lite?

O Lite custa $0,035 por imagem e tem resolução 2K/4K; o Pro é 1K/2K, com 2K a $0,10 por imagem. A forma de chamada é a mesma. Veja a comparação do mesmo prompt entre Flash e Lite em Seedream 5.0 Flash vs Lite.

É obrigatório usar callback?

Não. Scripts e tarefas em lote podem simplesmente usar polling, consultando a cada 5 segundos.

Você também pode copiar diretamente o prompt do letreiro neon acima e gerar uma imagem por $0,05.