API FASHN Try-On v1.6: exemplos de requisição curl e Python disponíveis

FASHN Try-On v1.6 é um modelo de provador virtual (image-to-image) no hiapi. Você fornece duas imagens — uma foto de uma pessoa e uma foto de uma peça de roupa — e ele retorna uma imagem composta mostrando a roupa vestida. Este artigo é um guia prático de fashn try-on api voltado a desenvolvedores: inclui uma requisição real para /v1/tasks que executei de ponta a ponta, o schema de entrada completo verificado junto ao validador de parâmetros online, e detalhes de produção que não estão na tabela de parâmetros.

Página do modelo e experiência online: FASHN Try-On v1.6.

1. O que você vai construir + pré-requisitos

Todo o fluxo segue o padrão de tarefa assíncrona: um POST cria a tarefa, depois você faz polling até a tarefa atingir o estado terminal e então baixa a imagem de saída.

Você precisa de:

• Uma API key (sk-...), obtida no início rápido do hiapi.
• Duas URLs de imagem publicamente acessíveis: a foto da pessoa para model_image e a foto da roupa para garment_image.

2. Exemplo mínimo funcional

Criar a tarefa (curl)

curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fashn-tryon-v1.6",
    "input": {
      "model_image": "https://cdn.example.com/person.jpg",
      "garment_image": "https://cdn.example.com/shirt.png"
    }
  }'

Resposta — esta é uma tarefa aceita, não a imagem final:

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

model_image e garment_image são os únicos campos obrigatórios; os demais campos têm valores padrão.

Consultar o resultado (curl)

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

Quando a tarefa termina, você obtém data.status: "success" e a imagem fica em data.output[0].url:

{
  "code": 200,
  "data": {
    "status": "success",
    "model": "fashn-tryon-v1.6",
    "storage": "temp",
    "output": [
      { "type": "image", "url": "https://temp.hiapi.ai/.../...-0.png", "expireAt": 1793119887 }
    ]
  },
  "message": "success"
}

O expireAt aqui é importante: a saída fica em armazenamento temporário (TTL de cerca de 7 dias). Baixe ou transfira esses bytes imediatamente — não faça hotlink diretamente.

Executar de ponta a ponta com Python

import time, requests

API = "https://api.hiapi.ai"
KEY = "sk-YOUR_KEY"
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

def try_on(model_image, garment_image, **opts):
    payload = {
        "model": "fashn-tryon-v1.6",
        "input": {"model_image": model_image, "garment_image": garment_image, **opts},
    }
    r = requests.post(f"{API}/v1/tasks", json=payload, headers=HEADERS, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    while True:                     # poll until terminal
        time.sleep(3)
        d = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        if d.get("status") == "success":
            return d["output"][0]["url"]
        if d.get("status") in ("fail", "error"):
            raise RuntimeError(f"task failed: {d}")

url = try_on(
    "https://cdn.example.com/person.jpg",
    "https://cdn.example.com/shirt.png",
    category="tops", mode="quality",
)
print(url)

3. Schema de entrada (verificado junto ao validador online)

O fashn-tryon-v1.6 usa um schema fechado — qualquer campo não listado abaixo será rejeitado, então você não consegue incluir parâmetros extras nativos do FASHN que o hiapi não expõe.

Campo	Obrigatório	Tipo	Valores aceitos
model_image	Sim	string (URL)	Foto da pessoa
garment_image	Sim	string (URL)	Foto da roupa
category	Não	enum	tops, bottoms, one-pieces, auto
mode	Não	enum	performance, balanced, quality
garment_photo_type	Não	enum	auto, model, flat-lay
output_format	Não	enum	png, jpeg
seed	Não	integer	Para reprodutibilidade
segmentation_free	Não	boolean	—

Como confirmei isso: enviar {"model":"fashn-tryon-v1.6","input":{}} retorna

invalid input: model_image: missing required field "model_image"; garment_image: missing required field "garment_image"

Cada valor de enum acima foi confirmado enviando um valor inválido, por exemplo mode: value must be one of 'performance', 'balanced', 'quality'. Enviar num_samples, num_images ou qualquer campo fora da tabela retorna additional properties '...' not allowed — não há opção de múltiplas amostras. Uma requisição retorna uma imagem; para obter resultados diferentes, varie o seed entre chamadas.

4. Práticas para produção

• A validação ocorre antes da cobrança. Uma entrada inválida retorna HTTP 400, com corpo {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: ..."}, e nenhuma tarefa é criada — requisições malformadas não geram custo. Uma requisição válida retorna code:200 com um taskId.
• Faça polling de novo, não reenvie. Cada POST /v1/tasks cria uma nova tarefa (cobrável). Se uma requisição de polling der timeout, continue consultando o taskId que você já tem; uma resposta perdida não significa que a tarefa falhou.
• Use callback em vez de polling. Para cenários em lote, você pode registrar um callback para que o hiapi notifique quando a tarefa atingir o estado final, sem precisar fazer polling por conta própria — consulte os campos específicos na documentação de referência da API assíncrona unificada. O exemplo acima usa polling.

5. O que aconteceu em uma execução real

Executei a requisição mínima acima — uma foto de pessoa de 768×1152 e uma imagem de roupa de 768×1152, omitindo mode e category:

• Latência: cerca de 13 segundos do created até o completed no objeto da tarefa.
• Saída: um único PNG, de 768×1152, ou seja, uma imagem em retrato. A página do modelo informa que o tamanho da saída acompanha a foto da pessoa (as execuções verificadas dela mediram 972×1296 e 768×1152), e esta execução está de acordo — não há campos width/height/aspect_ratio, portanto o tamanho da foto da pessoa determina o tamanho da saída.
• Caminho de status: durante o polling apareceu primeiro archiving, depois mudou para success; storage era temp.
• Os valores padrão funcionam de fato. Omitir mode e category ainda funcionou, então essas duas URLs de imagem são realmente as únicas entradas obrigatórias — o modelo identifica automaticamente o tipo de roupa.

A cobrança é pelo número de imagens de saída e não varia conforme o mode escolhido; consulte a página de preços para a tarifa atual.

Links relacionados

• Página do modelo FASHN Try-On v1.6 e experiência online
• Documentação de referência da API assíncrona (tarefas) unificada
• Início rápido — obter uma API key
• Preços

Perguntas frequentes

Quais campos são obrigatórios? Apenas model_image e garment_image, e ambos devem ser URLs publicamente acessíveis.

Posso gerar várias variantes em uma chamada? Não — num_samples e num_images são rejeitados pelo schema. Uma requisição retorna uma imagem; varie o seed entre chamadas para obter resultados diferentes.

Como controlar o tamanho da saída? Você não pode defini-lo diretamente. O resultado acompanha o tamanho da foto da pessoa — minha entrada de 768×1152 produziu uma saída de 768×1152.

Quanto tempo a URL do resultado fica válida? A saída fica em armazenamento temporário, com expireAt (cerca de 7 dias). Baixe esses bytes imediatamente.

O modo de qualidade muda o preço? Não — seja performance, balanced ou quality, a cobrança é pelo número de imagens de saída.