Search docs

Search the TryOnCloud API docs

Referência da API

Tarefas assíncronas, lotes e webhooks

POST /api/v1/generations e /batches, webhooks assinados, eliminação de clientes.

Os exemplos de código, os pontos de extremidade e os códigos de erro são os mesmos em todas as línguas.

POST /generate é a forma mais simples de executar uma simulação: basta uma solicitação e a imagem é devolvida. Utilize tarefas assíncronas quando não quiser manter uma ligação aberta e processamento em lote para trabalhos relacionados com o catálogo. Ambas utilizam o mesmo motor, têm o mesmo custo e reembolsam todas as simulações que falhem.

POST /generate (síncrono)POST /generations (assíncrono)POST /batches
RespostaO ficheiro PNG, no mesmo pedido202 com um ID de trabalho202 com um ID de lote
EntradasFicheiros, base64 ou garment_urlFicheiros, base64 ou URLsgarment_url e person_url por artigo
ResultadoCorpo da respostaGET /results/:id, mantido durante 7 diasO mesmo, por artigo
NotificaçãoNão é necessárioPoll ou webhookWebhook por item, além de batch.completed
CréditosQuota gratuita ou créditos compradosCréditos compradosCréditos comprados, cobrados para todos os itens ao criar o lote
Modo de teste?mock=true?mock=true?mock=true

Iniciar uma tarefa assíncrona

POST https://www.tryoncloud.com/api/v1/generations

Os mesmos cabeçalhos e campos de imagem que a opção Gerar, além de:

CampoDescrição
person_urlURL pública https da fotografia do comprador (alternativa a um ficheiro ou a um código base64)
customer_idO seu ID de utilizador final, com um máximo de 128 caracteres. Utilizado na eliminação de clientes
metadataUm objeto JSON com um tamanho máximo de 2 KB, devolvido sem alterações na tarefa e nos webhooks
webhook_urlURL pública https para receber generation.completed ou generation.failed
bash
curl -X POST https://www.tryoncloud.com/api/v1/generations \
  -H "X-API-KEY: $TRYONCLOUD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "garment_image=@shirt.jpg" \
  -F "person_image=@person.jpg" \
  -F "customer_id=shopper_123" \
  -F "webhook_url=https://example.com/hooks/tryoncloud"

202 Aceito

json
{
  "id": "6f0e3c1a-0d6a-4f7e-9a7b-2b2a1d3c4e5f",
  "object": "generation",
  "status": "queued",
  "mock": false,
  "batch_id": null,
  "customer_id": "shopper_123",
  "metadata": null,
  "result_id": null,
  "result_url": null,
  "error": null,
  "created_at": "2026-11-18T10:00:00.000Z",
  "completed_at": null
}

O processo tem início assim que a resposta é enviada. As suas imagens são processadas na memória e nunca são guardadas; apenas o resultado final é mantido, durante 7 dias.

Verificar uma oferta de emprego

GET https://www.tryoncloud.com/api/v1/generations/:id

O status passa de queued → processing → completed ou failed. Uma tarefa concluída tem um result_url; descarregue-o com a sua chave:

bash
curl https://www.tryoncloud.com/api/v1/results/RESULT_ID -H "X-API-KEY: $TRYONCLOUD_API_KEY" -o result.png

Uma tarefa com falha apresenta o código de erro error.code: CONTENT_FILTERED, GENERATION_FAILED ou INPUT_FETCH_FAILED. O crédito é reembolsado em todos os casos.

Lotes

POST https://www.tryoncloud.com/api/v1/batches, com um corpo JSON de até 500 itens:

json
{
  "items": [
    { "garment_url": "https://cdn.example.com/kurta-1.jpg", "person_url": "https://cdn.example.com/model-a.jpg", "customer_id": "sku-1001" },
    { "garment_url": "https://cdn.example.com/saree-7.jpg", "person_url": "https://cdn.example.com/model-b.jpg" }
  ],
  "webhook_url": "https://example.com/hooks/tryoncloud"
}
  • É deduzido um crédito por item quando o lote é criado. Se o seu saldo for demasiado baixo, nada é criado (código de erro 402 NO_CREDITS).
  • GET /batches/:id devolve o número de itens e cada um deles.
  • DELETE /batches/:id cancela os itens que ainda não foram iniciados e reembolsa-os. Os itens em execução são concluídos.
  • Cada item envia o seu próprio webhook, e o lote envia o batch.completed assim que todos os itens tiverem um resultado.

Webhooks

Enviamos um JSON via POST para o seu webhook_url:

json
{
  "event": "generation.completed",
  "created_at": "2026-11-18T10:00:21.000Z",
  "data": { "id": "6f0e3c1a-...", "object": "generation", "status": "completed", "result_url": "https://www.tryoncloud.com/api/v1/results/...", "customer_id": "shopper_123", "metadata": null }
}

Eventos: generation.completed, generation.failed, batch.completed e webhook.test no painel de controlo.

Cabeçalhos: x-tryoncloud-event, x-tryoncloud-delivery-id (eliminar duplicados neste), x-tryoncloud-timestamp e x-tryoncloud-signature-v2.

Endpoint da conta. Em vez de enviar o webhook_url em cada pedido, guarde um endpoint no painel de controlo (Chaves API > Webhooks) e selecione os eventos que este irá receber. O webhook_url próprio de cada pedido tem sempre prioridade. Envie um evento de teste assinado webhook.test para o endpoint guardado.

Verifique todas as entregas. O seu segredo de assinatura encontra-se no mesmo cartão (revele-o, copie-o ou rode-o). A assinatura é um HMAC-SHA256 de <timestamp>.<raw body>:

js
import crypto from "node:crypto"

export function verifyTryOnCloud(rawBody, headers, secret) {
  const ts = headers["x-tryoncloud-timestamp"]
  const sig = (headers["x-tryoncloud-signature-v2"] || "").replace("sha256=", "")
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false // reject old deliveries
  const expected = crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex")
  return sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
}

Responda com qualquer código 2xx no prazo de 8 segundos. Outras respostas e casos de tempo de espera esgotado são repetidos com intervalos de espera (1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas, 24 horas). Os URLs de webhook têm de ser públicos https na porta padrão; os endereços privados e internos são recusados, tanto quando guarda o URL como quando enviamos, e os redirecionamentos não são seguidos.

Eliminar os dados de um cliente

DELETE https://www.tryoncloud.com/api/v1/customers/:customer_id

Elimina todos os resultados armazenados para esse customer_id na sua conta e remove o ID dos seus registos. Utilize esta função quando um utilizador final solicitar o direito ao esquecimento (GDPR, DPDP).

json
{ "object": "customer_deletion", "customer_id": "shopper_123", "results_deleted": 3, "records_cleared": 4 }

Limites

Criação de tarefas e lotesConta para o limite de 300 pedidos por minuto por chave
Tarefas assíncronas a serem executadas simultaneamente50 por conta (429 TOO_MANY_JOBS); os lotes são separados
Tamanho do lote500 artigos
ResultadosGuardado durante 7 dias
MetadadosObjeto JSON, 2 KB