HiAPI
Pt
Blogue

Tutorial

Como usar o seedream-5.0-flash via hiapi API: curl, Python e uma requisição executável

Oct 8, 2026
Como usar o seedream-5.0-flash via hiapi API: curl, Python e uma requisição executável

O que você vai construir

Uma integração executável que chama o modelo de imagem seedream-5.0-flash da hiapi a partir de curl e Python: envia uma solicitação de geração de imagem a partir de texto (ou edição de imagem), consulta o resultado e baixa a URL de saída. Ao final, você terá um script pronto para usar no seu próprio projeto.

Pré-requisitos

  • Uma conta hiapi e uma chave de API. Obtenha no console da hiapi — a chave tem o formato sk-....
  • curl ou Python 3.8+ (pip install requests).
  • Nenhuma biblioteca de edição de imagem é necessária — seedream-5.0-flash aceita apenas um prompt, ou um prompt mais uma URL de imagem de entrada para edição.

Referência completa do modelo: seedream-5.0-flash na hiapi e a página de documentação da API.

Exemplo mínimo executável

A hiapi expõe todos os modelos de geração por meio de um endpoint unificado: primeiro você cria uma tarefa e depois consulta seu status (ou recebe um callback) até a conclusão.

curl

# 1. Criar tarefa
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-flash",
    "input": {
      "prompt": "a minimalist ceramic teapot on a wooden table, soft morning light, product photography",
      "size": "2K"
    }
  }'
# => {"code":0,"data":{"taskId":"task_xxx","status":"pending", ...}}

# 2. Consultar até concluir
curl -s https://api.hiapi.ai/v1/tasks/task_xxx \
  -H "Authorization: Bearer sk-<your-api-key>"
# => {"code":0,"data":{"taskId":"task_xxx","status":"success",
#      "output":[{"url":"https://...signed-url...","expireAt":"..."}]}}

Python

import time
import requests

API_KEY = "sk-<your-api-key>"
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def generate_image(prompt: str, size: str = "2K") -> str:
    create = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={"model": "seedream-5.0-flash", "input": {"prompt": prompt, "size": size}},
        timeout=30,
    )
    create.raise_for_status()
    task_id = create.json()["data"]["taskId"]

    while True:
        poll = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        poll.raise_for_status()
        data = poll.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task failed: {data}")
        time.sleep(2)


if __name__ == "__main__":
    image_url = generate_image("a minimalist ceramic teapot on a wooden table, soft morning light")
    print(image_url)

Notas sobre o objeto input:

  • prompt (obrigatório, 1–5000 caracteres) — o que gerar, ou o que modificar se você também passar image.
  • image (opcional, string ou array de até 10 URLs/base64 data:image/... URIs) — passe este parâmetro para editar/referenciar uma imagem existente em vez de gerar do zero. Omita para geração puramente a partir de texto.
  • size (opcional, padrão "2K") — um dos presets 1K / 1.5K / 2K, ou uma string personalizada WIDTHxHEIGHT como "1536x1024" (total de pixels entre 921.600 e 4.624.220, proporção entre 1:16 e 16:1).
  • output_format (opcional) — "jpeg" ou "png".
  • background (opcional, padrão "opaque") — defina como "transparent" apenas ao editar imagens com canal alfa.

O output[].url na resposta é um link assinado e que expira (campo expireAt) — baixe ou re-hospede prontamente, em vez de guardar esse hotlink por muito tempo.

Padrões para produção

Usar callback em vez de polling

Para integrações servidor-a-servidor, pule o polling e deixe a hiapi notificar você quando a tarefa for concluída. Adicione um objeto callback de nível superior ao lado de model/input (não aninhado dentro de input):

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-flash",
    "input": {"prompt": "a minimalist ceramic teapot on a wooden table"},
    "callback": {"url": "https://yourapp.example.com/hooks/hiapi", "when": "final"}
  }'

when: "final" é atualmente o único valor suportado — quando a tarefa atinge um estado terminal (success ou fail), seu endpoint recebe exatamente um POST. Para evitar reentregas, deduplique por taskId e confirme que seu endpoint é acessível via HTTPS antes de depender disso em produção.

Polling vs. callback

  • Use polling quando estiver fazendo protótipos, executando scripts de curta duração ou ainda não tiver um endpoint HTTPS público. É simples, mas adiciona latência e gera requisições para tarefas lentas.
  • Use callback quando estiver rodando um serviço — sem requisições de polling desperdiçadas, e você fica sabendo imediatamente quando a tarefa termina. Requer uma URL HTTPS publicamente acessível.

Idempotência

A geração de imagem em si não é idempotente (o mesmo prompt não retorna a mesma imagem duas vezes), então se seu fluxo de trabalho precisar de semântica de "retentativa sem cobrança duplicada", acompanhe o taskId do seu lado e verifique o status da tarefa antes de reenviar a mesma requisição após um timeout, em vez de retentar cegamente.

Tratamento de erros

  • 401 com permission_denied — sua chave de API está ausente, malformada ou foi revogada:

    {"error":{"code":"permission_denied","message":"This API key is invalid. Check that it is correct or use another API key and try again.","type":"hiapi_error"}}

    Verifique cuidadosamente se você está enviando Authorization: Bearer sk-... (e não apenas a chave bruta) e se a chave não foi rotacionada.

  • 400 com INVALID_REQUEST — algum campo não passou na validação. O message dirá exatamente qual campo e por quê, por exemplo um size fora do intervalo. Corrija o campo e reenvie; não retente como está.

  • Falha no nível da tarefa — a chamada HTTP pode ter sucesso (200) enquanto a tarefa termina com status: "fail" após o processamento. Sempre verifique data.status na resposta de polling/callback, não apenas o código de status HTTP da chamada de criação.

Links internos relacionados

Perguntas frequentes

O seedream-5.0-flash é gratuito? Não — ele é cobrado por imagem usando sua chave de API da hiapi. Consulte a página de preços para as tarifas atuais; não é possível acesso em produção sem uma chave válida.

O seedream-5.0-flash suporta edição imagem-para-imagem, não apenas texto-para-imagem? Sim. Adicione o campo image ao lado de prompt (uma URL ou string base64 data:image/..., ou um array de até 10), e o modelo editará/combinará com base na imagem de referência em vez de gerar do zero.

Por que minha requisição retorna 200 mas nenhuma imagem? POST /v1/tasks retornar 200 significa apenas que a tarefa foi aceita — a geração é assíncrona. Consulte GET /v1/tasks/<id> (ou aguarde o callback) e verifique data.status; a URL da imagem só aparece quando status é "success".

Posso solicitar uma resolução personalizada em vez de 1K/1.5K/2K? Sim — passe size como "WIDTHxHEIGHT" (por exemplo "1536x1024") em vez de um preset. O total de pixels deve estar entre 921.600 e 4.624.220, e a proporção entre 1:16 e 16:1, caso contrário a requisição retorna 400.

O que acontece com a URL de saída depois de um tempo? O output[].url retornado é uma URL assinada com carimbo de data/hora expireAt — não é armazenamento permanente. Baixe os bytes ou copie para seu próprio armazenamento assim que a tarefa for concluída com sucesso.

Meu callback nunca disparou — o que devo verificar primeiro? Confirme que seu callback.url é um endpoint HTTPS publicamente acessível (não localhost ou endereço apenas interno) e que callback é um campo de nível superior no corpo da requisição — não aninhado dentro de input.

EtiquetasseedreamGeração de ImagensTutorial de APIpythoncurl

Artigos relacionados

Ver todos os artigos →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API