Como usar a API wan2.7-image-standard no hiapi: geração de imagens a partir de texto e edição com imagem de referência

wan2.7-image-standard é o nível padrão do modelo Tongyi Wanxiang Wan 2.7 Image. O motivo pelo qual vale a pena dedicar uma página separada a ele: um único ID de modelo oferece suporte tanto à geração de imagens a partir de texto quanto à edição de imagens baseada em imagem de referência, com suporte máximo de 2K, cobrado a preço fixo de US$ 0,0345 por imagem — mais barato que o nível Pro com suporte a 4K. Este guia traz uma requisição pronta para executar, o schema de entrada exato (verificado contra a API online), o caminho de edição com imagem de referência e os comportamentos de borda que você precisa tratar em produção.

Todo o conteúdo das seções de schema e erros abaixo foi confirmado durante a escrita sondando o endpoint /v1/tasks online — as listas de enum, os conjuntos de campos aceitos e as formas das respostas de falha são citados de respostas reais da API, não de memória.

O que você vai construir e o que precisa preparar

Você enviará um prompt (opcionalmente com uma imagem de referência), fará polling até a tarefa ser concluída e então baixará a imagem. Primeiro você precisa de uma coisa: obter uma API key no início rápido do hiapi e exportá-la como HIAPI_API_KEY. Não existe caminho sem key — toda requisição é autenticada via Authorization: Bearer sk-<your-key>.

wan2.7-image-standard roda na API de tarefas assíncronas do hiapi: primeiro você faz POST /v1/tasks para criar a tarefa, depois faz polling no endpoint de detalhes até que ele reporte um estado terminal.

Geração a partir de texto: requisição mínima

Criar a tarefa:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-standard",
    "input": {
      "prompt": "Hora azul após a chuva, num beco silencioso e vazio há um pequeno estúdio de cerâmica, com lanternas de papel quentes penduradas, bule esmaltado na vitrine, luz refletida na calçada de pedra molhada, uma bicicleta encostada na parede, fotografia cinematográfica 35mm, alto nível de detalhes",
      "aspect_ratio": "16:9",
      "resolution": "2K"
    }
  }'

O id da tarefa na resposta fica em data.taskId:

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

Em seguida, faça polling em GET /v1/tasks/<taskId> até que data.status seja success, e leia a URL da imagem em data.output[0].url:

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def generate(prompt, aspect_ratio="16:9", resolution="2K", image_urls=None, timeout=600):
    payload = {"model": "wan2.7-image-standard",
               "input": {"prompt": prompt,
                         "aspect_ratio": aspect_ratio,
                         "resolution": resolution}}
    if image_urls:                      # edição com imagem de referência (ver próxima seção)
        payload["input"]["image_urls"] = image_urls

    create = requests.post(API, headers=HEADERS, json=payload).json()
    if create.get("code") != 200:       # erros de validação síncrona (por exemplo, valor de enum inválido)
        raise RuntimeError(create)
    task_id = create["data"]["taskId"]

    deadline = time.time() + timeout
    while time.time() < deadline:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
        if data["status"] == "success":
            return requests.get(data["output"][0]["url"]).content
        if data["status"] == "fail":    # falha terminal — não continue o polling
            raise RuntimeError(data.get("error"))
        time.sleep(5)
    raise TimeoutError(task_id)

png = generate("...")   # salve os bytes imediatamente — veja a nota sobre expiração abaixo

aspect_ratio e resolution são opcionais (o modelo tem valores padrão), mas defina-os explicitamente — resolution aceita apenas 1K ou 2K, e ambos custam o mesmo, então não há motivo de custo para deixá-lo no padrão.

Edição com imagem de referência: o mesmo ID de modelo, mais image_urls

É aqui que o nível padrão se diferencia do Pro. Passe imagens de referência em image_urls (um array, com até 9 imagens de referência conforme a especificação do modelo), e o modelo editará ou recomporá com base nelas, ainda seguindo seu prompt de texto:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-standard",
    "input": {
      "prompt": "Coloque este produto sobre uma bancada de cozinha de mármore iluminada pelo sol, com ervas frescas ao lado, luz suave da manhã, fotografia de produto lifestyle",
      "image_urls": ["https://your-storage.example.com/product.jpg"],
      "resolution": "2K"
    }
  }'

Em Python, é apenas o parâmetro image_urls=[...] passado à função auxiliar acima — nada mais muda. Mesmo com imagens de referência, prompt continua obrigatório (a API rejeita requisições sem prompt: missing required field "prompt").

O nome do campo importa: é image_urls. Alternativas que parecem razoáveis — reference_image_urls, image_input, input_urls — são todas rejeitadas pelo schema com additional properties '<name>' not allowed. Se você está portando código de endpoints de edição de outros modelos, este é o primeiro ponto a corrigir.

O schema de entrada exato

O schema é estrito: qualquer campo fora da lista abaixo retorna 400 INVALID_REQUEST com additional properties '<name>' not allowed. Estes são todos os campos que ele aceita:

Campo	Tipo	Obrigatório	Descrição
prompt	string	sim	Obrigatório tanto para geração a partir de texto quanto para edição. Pode ser em inglês ou chinês.
aspect_ratio	string enum	não	Um dos seguintes: 1:1, 16:9, 4:3, 21:9, 3:4, 9:16, 8:1, 1:8. Qualquer outro valor (por exemplo, 3:2) → 400.
resolution	string enum	não	Apenas 1K ou 2K. Este nível não suporta 4K.
image_urls	string[]	não	Imagens de referência para edição (até 9). Informá-las alterna para o modo de referência.
seed	integer	não	Para saídas reproduzíveis.

Campos que você pode imaginar, mas que este modelo não aceita: negative_prompt, n, size e prompt_optimizer são todos rejeitados como propriedades desconhecidas. Não há parâmetro de lote (n) — envie uma tarefa por imagem.

Considerações de produção e comportamento observado

Retornar 200 no envio não significa que a imagem será gerada. wan2.7-image-standard valida valores de enum de forma síncrona (um resolution ou aspect_ratio incorreto faz o POST falhar imediatamente com 400 INVALID_REQUEST), mas não valida as URLs de referência no momento do envio. Entradas malformadas ou inacessíveis em image_urls são aceitas, retornam 200 e um taskId, e então a tarefa falha cerca de um segundo depois. Verifiquei isso diretamente: uma tarefa criada com uma URL de referência inválida retornou o seguinte estado terminal

{ "status": "fail", "error": { "code": "INVALID_REQUEST", "message": "invalid request parameters for this model" } }

A consequência prática: sempre faça polling até o estado terminal e trate pelo ramo data.status == "fail" (lendo data.error). Tarefas com falha são reportadas como HTTP 200 com data.status: "fail" — a informação de falha fica em data.error, não em um erro HTTP de nível superior. Antes de enviar, certifique-se de que suas URLs de referência sejam acessíveis publicamente.

Baixe a saída imediatamente. data.output[0].url é um link temporário com carimbo de tempo expireAt, não um recurso permanente de CDN. Obtenha os bytes no instante em que a tarefa for concluída e transfira-os para o seu próprio armazenamento; URLs expiradas retornam 404. Se você já enfrentou esse problema, consulte por que sua URL de saída do hiapi retorna 404 e como lidar com isso.

Polling vs. callback. O exemplo acima faz polling a cada cinco segundos, o que serve para scripts e lotes pequenos. Para throughput de produção, anexe callback à requisição de criação, para que o hiapi notifique você nos eventos de estado terminal em vez de você manter a conexão aberta — veja a documentação de criação de tarefas para o mecanismo específico.

Padrão vs. Pro: qual nível chamar

O hiapi hospeda dois níveis do Wan 2.7 Image, que são IDs de modelo distintos, não parâmetros:

• wan2.7-image-standard (este guia) — geração a partir de texto e edição com imagem de referência, 1K/2K, cobrado a preço fixo de US$ 0,0345 por imagem independentemente da resolução.
• wan2.7-image/text-to-image — nível Pro: apenas geração a partir de texto, até 4K, preço fixo de US$ 0,08 por imagem. Veja a página do Wan 2.7 Image Pro e o guia detalhado sobre como usá-lo para gerar imagens de produto de e-commerce em 4K.

Escolha o nível padrão quando precisar de edição com imagem de referência, ou quando 2K for suficiente e você quiser pagar menos da metade do preço por imagem do Pro. Use o Pro apenas quando precisar especificamente de saída nativa em 4K — é a única coisa que o nível padrão não faz. Consulte a página de preços para os preços atuais de ambos.

Perguntas frequentes

O wan2.7-image-standard suporta edição de imagens ou apenas geração a partir de texto? Ambos, a partir do mesmo ID de modelo. Adicione o array image_urls para alternar para a edição com imagem de referência; omita-o para geração pura a partir de texto.

Qual é a resolução máxima? 2K. O campo resolution aceita apenas 1K e 2K; a API online rejeita qualquer outro valor. Se você precisa de 4K, use o nível Pro (wan2.7-image/text-to-image).

Por que minha tarefa retornou 200 e depois falhou? As URLs de referência não são verificadas no envio — apenas na execução. Entradas inacessíveis ou malformadas em image_urls criam a tarefa (HTTP 200) e depois falham em estado terminal com INVALID_REQUEST. Faça polling em data.status e verifique se suas URLs são públicas.

Posso definir um prompt negativo? Não. negative_prompt não é um campo aceito por este modelo (assim como n, size ou prompt_optimizer). Oriente por meio do prompt positivo e do seed.