Guia da API Seedream 5.5: preços, parâmetros e exemplos de chamada

O que o Seedream 5.5 faz

O Seedream 5.5 é um modelo de imagem na HiAPI; um único ID de modelo (seedream-5.5) cobre dois usos: basta escrever um prompt para gerar imagem a partir de texto; anexe imagens de referência para editar conforme a referência ou preservar o conteúdo da cena. Os dois usos passam pela mesma interface e pelo mesmo conjunto de parâmetros; a diferença está apenas em haver ou não image_urls na requisição.

Cada chamada retorna uma imagem. A seguir explicamos na ordem "como o preço é calculado → como preencher os parâmetros → como enviar a requisição → quais são as limitações"; todos os números seguem a definição da interface no momento em que este artigo foi escrito.

Preço: cobrança por faixa de pixels, com acréscimo por imagem de referência

O custo é composto por duas partes: o preço base da faixa de saída, mais a taxa das imagens de referência.

• 1K / 1.5K: $0.0186 / imagem
• 2K (faixa padrão): $0.0325 / imagem
• Imagem de referência: $0.0075 por imagem, a primeira também é cobrada, no máximo 10

Alguns exemplos:

• 1K, geração de imagem a partir de texto, sem imagem de referência: $0.0186
• 2K, com 1 imagem de referência: $0.0325 + $0.0075 = $0.04
• 2K, com 10 imagens de referência (limite): $0.0325 + $0.075 = $0.1075

Sem size, a imagem é gerada em 2K e cobrada como 2K. Se for apenas para rascunho ou imagem auxiliar em tamanho pequeno, declarar explicitamente "size": "1K" economiza cerca de 40%. Em caso de falha da tarefa, o valor é reembolsado integralmente.

Visão geral dos parâmetros

Exceto model e prompt, todos são opcionais:

• prompt: obrigatório, de 1 a 5000 caracteres. Descreve a cena a ser gerada; com imagens de referência, deixe claro o que deve ser alterado e o que deve ser preservado.
• size: 1K, 1.5K, 2K; padrão 2K.
• aspect_ratio: 10 opções — 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9, 2:1, 1:2. Se omitido, o modelo escolhe automaticamente com base no prompt e nas imagens de referência.
• image_urls: de 1 a 10 endereços de imagem http(s) acessíveis publicamente. Se omitido, é geração puramente a partir de texto.
• output_format: png ou jpeg; padrão png.
• background: auto, transparent, opaque; padrão auto. Com transparent, o formato de saída só pode ser png; combinado com jpeg, será rejeitado.

Enviar uma requisição

As tarefas de imagem da HiAPI são assíncronas: primeiro crie a tarefa, depois consulte o resultado. O model fica no nível superior; os demais parâmetros vão em input.

Geração de imagem a partir de texto (2K, 16:9):

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.5",
    "input": {
      "prompt": "Farol à beira-mar ao amanhecer, névoa leve, luz lateral suave, estilo fotografia realista",
      "size": "2K",
      "aspect_ratio": "16:9"
    }
  }'

Edição com imagem de referência (1K, fundo transparente, PNG):

{
  "model": "seedream-5.5",
  "input": {
    "prompt": "Preserve o corpo da garrafa e o rótulo, remova o fundo e troque por uma luz superior suave",
    "image_urls": ["https://example.com/bottle.jpg"],
    "size": "1K",
    "background": "transparent",
    "output_format": "png"
  }
}

O custo deste pedido é $0.0186 + $0.0075 = $0.0261. Após a criação bem-sucedida, use o ID de tarefa retornado para chamar GET https://api.hiapi.ai/v1/tasks/{taskId} em polling; quando o status mudar para sucesso, obtenha o endereço da imagem na saída para baixá-la.

Limitações atuais

• Máximo de 2K; não há faixa 4K.
• Não suporta saída de imagem em camadas.
• Cada chamada gera apenas uma imagem; para várias, envie múltiplas tarefas em paralelo.
• As imagens de referência devem ser endereços http(s) acessíveis na internet pública; não são aceitos caminhos de arquivo local nem base64.
• Fundo transparente só é suportado em PNG.

Como escolher a faixa

Para pôsteres que vão direto ao ar e imagens principais de produtos, use o padrão 2K; para rascunhos de revisão interna, testes em lote de estilo e miniaturas pequenas, use 1K ou 1.5K (ambos têm o mesmo preço; 1.5K é mais nítido, então se não houver motivo para escolher 1K, use 1.5K diretamente). As imagens de referência são cobradas por unidade; inclua apenas aquelas que realmente influenciam o resultado; para várias imagens de um mesmo produto em ângulos diferentes, teste primeiro com 1–2 e acrescente se o efeito não for suficiente.