Como usar o seedream-5.0-pro/image-to-image via API hiapi: curl, Python e um exemplo de requisição executável

O Seedream 5.0 Pro é o modelo de imagem de destaque da ByteDance, e seu endpoint de imagem para imagem (image-to-image) recebe uma ou mais imagens de referência e uma instrução em texto, retornando o resultado editado — reestilização, troca de fundo, limpeza de fotos de produto, composição com múltiplas imagens. Na hiapi, ele roda sobre a API unificada de tarefas assíncronas: você cria a tarefa, depois faz polling (ou recebe callback) e, por fim, baixa a saída. Cada parâmetro, valor de enum e mensagem de erro abaixo foi verificado contra a API em produção antes da publicação deste guia.

O que você vai construir e o que precisa preparar

Objetivo: enviar uma imagem de referência e uma instrução de edição para seedream-5.0-pro/image-to-image, recuperar a imagem editada e salvá-la localmente.

Você precisa preparar duas coisas:

1. Uma chave de API da hiapi — obtenha no seu console. Ela precisa ir no cabeçalho Authorization: Bearer sk-....
2. URLs de imagem acessíveis publicamente — a API busca suas imagens de referência no servidor, portanto elas precisam estar acessíveis via HTTPS. URLs pré-assinadas geradas pelo seu próprio bucket funcionam perfeitamente; localhost ou caminhos privados não funcionam. Se a URL não puder ser buscada, você receberá um erro normalizado, e não uma falha silenciosa.

Parâmetros (verificados)

O ID do modelo é seedream-5.0-pro/image-to-image, exatamente como retornado por GET /v1/models. Todos os quatro campos de entrada são obrigatórios:

Campo	Tipo	Obrigatório	Valores / descrição
prompt	string	Sim	Instrução de edição.
image_urls	array de strings	Sim	1–10 URLs de imagem acessíveis publicamente. Sempre um array, mesmo que haja apenas uma imagem.
aspect_ratio	string	Sim	match_input_image, 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9
resolution	string	Sim	1K ou 2K

Há dois pontos propensos a erro:

• O schema é estrito. Campos desconhecidos são rejeitados — enviar n, size ou seed retorna 400 com additional properties ... not allowed. Na hiapi, o schema de entrada de cada modelo é diferente (alguns usam size, outros usam aspect_ratio), portanto não copie campos entre famílias de modelos.
• Aqui, resolution aceita somente 1K/2K. Outros endpoints seedream aceitam conjuntos de resolução diferentes, então vale confirmar endpoint por endpoint em vez de supor.

Exemplo mínimo executável: curl

Criar a tarefa:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
      "prompt": "Turn this product photo into a clean studio shot on a seamless white background with soft shadows",
      "image_urls": ["https://your-bucket.example.com/product.jpg"],
      "aspect_ratio": "match_input_image",
      "resolution": "2K"
    }
  }'

Quando a criação é bem-sucedida, o ID da tarefa é retornado em data.taskId (resposta simplificada):

{ "data": { "taskId": "<your-task-id>" } }

Faça polling até a tarefa entrar em estado terminal:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

data.status termina em success — sua URL de imagem fica em data.output[0].url — ou em fail, com detalhes em data.error.code e data.error.message.

Script Python completo: criar, fazer polling, baixar

Usa apenas a biblioteca padrão — não precisa instalar nada:

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-YOUR_KEY"


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


# 1. Create the edit task
create = call(API, {
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
        "prompt": "Restyle this living room as a Scandinavian interior, keep the layout and window positions",
        "image_urls": ["https://your-bucket.example.com/room.jpg"],
        "aspect_ratio": "match_input_image",
        "resolution": "2K",
    },
})
task_id = create["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until terminal state
while True:
    task = call(f"{API}/{task_id}")["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
    time.sleep(5)

# 3. Download immediately -- output URLs expire
image_url = task["output"][0]["url"]
urllib.request.urlretrieve(image_url, "edited.png")
print("saved edited.png")

Considerações para produção

Em servidores, prefira callbacks ao polling. Ao criar a tarefa, adicione um objeto callback de nível superior, e a hiapi fará um POST único para o seu endpoint quando a tarefa entrar em estado terminal:

{
  "model": "seedream-5.0-pro/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-server.example.com/hiapi-hook", "when": "final" }
}

No handler, trate o callback como um sinal, não como fonte de verdade: extraia o ID da tarefa, faça você mesmo uma nova requisição GET /v1/tasks/<id> e só então aja com base nela. Para scripts, notebooks e tarefas pontuais, o polling continua sendo a escolha adequada — basta manter o intervalo em torno de 5 segundos.

Torne as retentativas idempotentes. Ao criar a tarefa, salve seu próprio mapeamento de imagem de origem → taskId. Se o processo cair no meio do polling, reassocie ao taskId salvo em vez de reenviar a edição — o reenvio gera uma segunda tarefa cobrada.

Baixe a saída imediatamente. A URL em data.output[0].url é temporária (tem prazo de expiração). Baixe os bytes e armazene no seu próprio bucket; nunca faça hotlink da URL de saída da tarefa em conteúdo voltado ao usuário.

Erros que você realmente vai encontrar:

• 401 com permission_denied — chave de API ausente ou malformada. Verifique se o cabeçalho é exatamente Authorization: Bearer sk-....
• 400 com INVALID_REQUEST — violação do schema de entrada. As mensagens de erro são precisas, por exemplo resolution: value must be one of '1K', '2K' ou image_urls: maxItems: got 11, want 10.
• image_urls must be an array — você passou uma string solta. Mesmo que haja apenas uma imagem, coloque-a dentro de uma lista.

Próximos passos

• Página do modelo: seedream-5.0-pro/image-to-image — capacidades e status atual.
• O preço por imagem está listado na página de preços.
• Opção de edição mais barata para pipelines de alta concorrência: como usar o seedream-5.0-lite de imagem para imagem.
• Para escolher entre modelos: as melhores APIs de imagem para imagem de 2026 compara a mesma tarefa de edição em três modelos.
• Referência completa da API: documentação da hiapi.

Perguntas frequentes

Quantas imagens de referência posso enviar no máximo? Até 10 URLs em image_urls. O limite é aplicado no servidor — 11 imagens retornam maxItems: got 11, want 10.

A saída pode manter a proporção da imagem de entrada? Sim — defina aspect_ratio como match_input_image. Para edições e reestilizações, geralmente é isso que você quer; só escolha uma proporção explícita como 16:9 quando estiver deliberadamente recompondo o enquadramento.

O seedream-5.0-pro image-to-image suporta 4K? Não. Este endpoint aceita somente 1K e 2K. Se você solicitar qualquer outro valor, receberá 400 com a lista de valores permitidos.

Minhas URLs de imagem precisam ser públicas? Elas precisam ser buscáveis pelos servidores da hiapi via HTTPS. URLs pré-assinadas (S3, R2, GCS) funcionam bem e permitem manter o bucket em si privado.

Quanto custa cada imagem no seedream-5.0-pro image-to-image? A cobrança é por imagem gerada com sucesso e varia conforme a resolução — consulte a página de preços em tempo real para as tarifas atuais.

Qual é a diferença em relação ao seedream-5.0-lite image-to-image? O Pro é o nível de destaque, voltado a edições mais difíceis e de maior fidelidade; o lite é a opção mais rápida e barata para grandes volumes. A estrutura da requisição é semelhante, então a forma mais clara de decidir é rodar a mesma tarefa de edição nos dois — comece pelo guia do lite e compare os resultados com suas próprias imagens de referência.