Tutorial
Como usar seedream-4.5/text-to-image pela API HiAPI: exemplos em curl e Python
Guia prático para desenvolvedores com integração mínima executável
Nesta página
O que seedream-4.5/text-to-image oferece
seedream-4.5/text-to-image é um endpoint de geração de imagem a partir de texto disponibilizado pela API HiAPI. Você envia um prompt de texto e alguns parâmetros opcionais, e o modelo retorna uma imagem gerada. Use-o para criar ilustrações de cenas, mockups de produtos, arte conceitual ou qualquer conteúdo visual que precise renderizar texto legível dentro da imagem — letreiros, rótulos, títulos curtos. O endpoint é stateless: cada requisição é uma geração independente, portanto o controle de repetição e variação fica no código da sua aplicação.
Como ele roda atrás da mesma interface unificada dos demais modelos HiAPI, você se autentica uma vez, usa a mesma URL base e as mesmas convenções de erro, e não precisa aprender um novo padrão de integração ao trocar de modelo. A página de detalhes do modelo seedream-4.5/text-to-image lista os nomes de parâmetros e os valores aceitos atuais — use essa página como fonte autoritativa dos campos, não este artigo.
Estrutura da requisição: o que enviar e o que receber
Toda chamada de geração de imagem a partir de texto tem a mesma estrutura: um POST para o endpoint HiAPI do modelo com um corpo JSON. O corpo contém os campos exigidos pelo modelo; a resposta contém a imagem gerada e metadados sobre a requisição.
O que enviar
prompt(string, obrigatório): a descrição da imagem. É a principal superfície de controle; veja a seção de prompt abaixo.aspect_ratioou algum campo relacionado a dimensões (opcional): controla o formato da tela de saída. Use o nome exato do campo na página de detalhes do modelo — não presuma que ele corresponda ao de outros modelos.- Quaisquer opções específicas do modelo documentadas na página (por exemplo, dicas de estilo ou qualidade). Omita os campos de que não precisa; a API aplica os padrões.
O que receber
Uma resposta bem-sucedida é um objeto JSON. Os campos que você realmente lê no código costumam ser:
- A carga da imagem: dependendo do esquema de resposta, pode ser a URL da imagem gerada ou uma string de imagem codificada em base64. Seu código deve lidar com a forma que o endpoint realmente retorna; a página do modelo informa qual é.
- Metadados da requisição, como identificadores ou status, úteis para registro em log e suporte.
Nem todo campo é garantido em todas as versões, então valide a estrutura da resposta em vez de presumir um schema fixo. Se você construir um parser que busca apenas os campos de que precisa e trata os demais como opcionais, sua integração resistirá a pequenas variações de resposta.
Sua primeira requisição curl executável
A chamada mínima válida envia apenas um prompt, nada mais. Substitua a chave e o prompt de exemplo pelos seus e execute.
curl -X POST "https://api.hiapi.ai/v1/models/seedream-4.5/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "um café de rua tranquilo ao entardecer, luz quente nas janelas, uma lousa com a palavra OPEN",
"aspect_ratio": "1:1"
}'
Explicação linha a linha:
- A URL aponta para o endpoint HiAPI do modelo. Mantenha o identificador do modelo exatamente como na documentação.
- O cabeçalho
Authorizationcarrega sua chave de API. Usar variáveis de ambiente mantém a chave fora do histórico do shell e dos arquivos-fonte. Content-Type: application/jsoninforma ao servidor que interprete o corpo como JSON.- O corpo JSON contém o prompt e uma proporção de aspecto opcional. Comece com uma imagem e um prompt; itere a redação antes de adicionar opções.
Se a chamada for bem-sucedida, a resposta conterá os dados de imagem descritos na seção anterior. Salve a saída em arquivo (ou abra a URL retornada) e inspecione antes de construir mais coisas. Se receber erro de autenticação, confirme que a chave existe e que o cabeçalho está grafado corretamente; se receber erro de parâmetro, revalide os nomes de campo na página do modelo.
A mesma requisição em Python
A versão em Python usa a biblioteca padrão requests — sem SDK.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/models/seedream-4.5/text-to-image"
payload = {
"prompt": "um café de rua tranquilo ao entardecer, luz quente nas janelas, uma lousa com a palavra OPEN",
"aspect_ratio": "1:1",
}
response = requests.post(
URL,
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
response.raise_for_status()
result = response.json()
print(result)
Dois detalhes importam aqui. Primeiro, passe json=payload em vez de uma string montada à mão — o requests define o tipo de conteúdo e serializa corretamente. Segundo, defina um timeout explícito. A geração de imagem pode levar mais tempo do que uma chamada de API típica, então um timeout generoso com um modo de falha claro é melhor do que uma requisição pendurada.
O resultado impresso é a resposta bruta. No código real, extraia o campo de imagem retornado pelo seu endpoint (URL ou base64) e então baixe a URL com uma segunda requisição ou decodifique o base64 em bytes e grave em disco. Coloque essa lógica de extração em uma função auxiliar pequena, para que testes e código de produção compartilhem a mesma lógica de parsing.
Escrevendo prompts para realismo e texto legível
A qualidade do prompt determina a qualidade da saída mais do que qualquer outro parâmetro. Os dois objetivos mais frequentes são: cenas fotorrealistas e texto nítido e legível dentro da imagem.
Realismo
Descreva a cena como um fotógrafo enquadraria: sujeito, iluminação, hora do dia, sensação de lente e ambiente. Substantivos concretos vencem adjetivos abstratos. Em vez de “uma cafeteria agradável”, escreva “o interior estreito de uma cafeteria, luz do meio-dia entrando por janelas grandes, balcão de madeira, profundidade de campo rasa”. Adicione uma dica curta de estilo, como “photograph” ou “documentary photo”, para afastar o modelo do estilo ilustração. Mantenha um sujeito principal por prompt; sujeitos concorrentes costumam produzir composições confusas.
Texto legível
Quando a imagem precisar conter texto, coloque o texto exato entre aspas e mantenha-o curto. Uma lousa com OPEN ou um rótulo com FRESH BREAD é muito mais confiável do que um parágrafo inteiro. Indique onde o texto aparece — “uma lousa acima do balcão com a palavra OPEN” — para que o modelo saiba que o texto pertence a um objeto. Se o texto sair com caracteres embaralhados, encurte-o, simplifique a cena ao redor e gere novamente. Ajustes pequenos de redação são normais; espere algumas iterações.
Iteração
Mude uma variável por vez: primeiro o prompt, depois a proporção de aspecto, depois quaisquer opções de estilo. Guarde seus prompts e as configurações que produziram bons resultados. Esse registro será sua linha de base para regeração e evitará que a depuração vire adivinhação.
Escolhendo proporção de aspecto e configurações de saída
A proporção de aspecto define a composição antes de o modelo desenhar qualquer coisa. Escolha com base no uso final, não para corresponder ao padrão.
- Quadrado (
1:1): posts sociais, avatares, blocos de produto. Simples e seguro. - Paisagem (por exemplo,
16:9): banners, imagens principais, slides de apresentação. Favorece cenas amplas — horizontes, fachadas, interiores espaçosos. - Retrato (por exemplo,
9:16): telas de celular, stories, pôsteres. Prompts com um sujeito vertical claro — uma pessoa em pé, um prédio alto — funcionam melhor.
Se seu prompt descreve uma cena ampla mas você pede uma tela vertical, o modelo terá de cortar ou distorcer a composição. Faça a descrição corresponder ao formato. Para pipelines downstream, gere no tamanho adequado ao seu maior caso de uso e reduza depois; ampliar imagens pequenas raramente parece correto. Quando precisar de vários formatos, faça chamadas separadas por proporção em vez de recortar uma imagem em diferentes layouts.
Configurações de saída além da proporção de aspecto (dicas de qualidade, controles de estilo) são específicas do modelo. Defina apenas o que a página do modelo documenta e trate cada parâmetro extra como uma variável a testar, não como um padrão a copiar.
Tratando erros e limites de taxa
As falhas de uma integração em produção são previsíveis: chave errada, parâmetro inválido, timeout e limitação de taxa. Trate cada categoria explicitamente.
Valide antes de fazer parsing
Verifique primeiro o código de status HTTP. 2xx significa sucesso — então faça o parsing do corpo. 4xx normalmente indica problema na sua requisição: chave não autorizada, JSON malformado ou valor de parâmetro não suportado. Esses problemas não se resolvem com retry; registre o corpo da resposta, reporte ao chamador e corrija a requisição. 5xx indica problema no servidor, geralmente temporário.
Retry com backoff
Repita apenas falhas que possam ter sucesso depois: respostas 429, timeouts, erros de conexão e a maioria dos códigos 5xx. Use backoff exponencial com jitter — espere um intervalo base curto, dobre a cada tentativa e limite o total de tentativas. Nunca repita 400 ou 401; você só consumirá cota à toa.
import time, random
def generate(payload, max_attempts=5):
for attempt in range(max_attempts):
try:
r = requests.post(URL, headers=HEADERS, json=payload, timeout=60)
except requests.RequestException:
pass # erro de rede: tenta novamente abaixo
else:
if r.status_code == 200:
return r.json()
if r.status_code not in (429, 500, 502, 503, 504):
raise RuntimeError(f"irrecuperável: {r.status_code} {r.text}")
time.sleep(min(2 ** attempt + random.random(), 30))
raise RuntimeError("tentativas esgotadas")
Respeite os limites
Mantenha o volume de requisições abaixo do limite de taxa indicado na sua conta e trate 429 como sinal para desacelerar, não para tentar com mais força. Adicione um teto de concorrência nos workers e registre o ID da requisição a cada tentativa, para poder diagnosticar limitações e falhas depois. Como chamadas de imagem são cobradas pela saída gerada, retries que produzem imagens não são gratuitos — valide a entrada antes de enviar a requisição.
Da chamada de teste ao checklist de produção
Antes de ir ao ar, confirme os seguintes pontos operacionais:
- Gestão de chaves: chaves em variáveis de ambiente ou gerenciador de segredos, nunca no controle de versão. Rotacione as chaves periodicamente e imediatamente em qualquer suspeita de vazamento.
- Timeouts: toda chamada de saída tem timeout explícito, e seu chamador tem um plano para quando o timeout dispara.
- Logs: registre o ID da requisição, a versão do prompt, os parâmetros, o status e a latência a cada chamada. Masque chaves e payloads completos quando necessário.
- Versionamento de prompts: guarde os prompts e as configurações que produziram saídas aceitas, para reproduzir e reverter.
- Consciência de custo: a geração é cobrada pela saída, então limite o tamanho dos lotes, evite retries desnecessários e faça cache dos resultados que for reutilizar.
- Degradação graciosa: quando a geração falhar após os retries, recorra a uma imagem em cache ou a um placeholder em vez de quebrar a página.
Comece com a chamada curl única deste guia, mova-a para uma função auxiliar pequena em Python e só então adicione concorrência e processamento em lote. Ao escalar a integração, a página de referência do modelo seedream-4.5/text-to-image é o lugar para confirmar nomes de campos.
Artigos relacionados
Ver todos os artigos →-
Tutorial
Guia prático do gpt-6.2-sol: 5 usos de alto valor de modelos de texto nos negócios
-
Tutorial
Guia prático do gpt-6.2-astra: pontos de integração e implementação em 5 cenários de texto de alto valor
Uma lista de verificação do ponto de vista do desenvolvedor, da seleção de cenários à implementação em engenharia
-
Tutorial
Cenários práticos do Tripo H3.1: 5 usos de alto valor e pontos de implementação
De texto para 3D à reconstrução multivisão: escolha o modo e os parâmetros certos para cada cenário de negócio