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 | |
|---|---|---|---|
| Resposta | O ficheiro PNG, no mesmo pedido | 202 com um ID de trabalho | 202 com um ID de lote |
| Entradas | Ficheiros, base64 ou garment_url | Ficheiros, base64 ou URLs | garment_url e person_url por artigo |
| Resultado | Corpo da resposta | GET /results/:id, mantido durante 7 dias | O mesmo, por artigo |
| Notificação | Não é necessário | Poll ou webhook | Webhook por item, além de batch.completed |
| Créditos | Quota gratuita ou créditos comprados | Créditos comprados | Cré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:
| Campo | Descrição |
|---|---|
person_url | URL pública https da fotografia do comprador (alternativa a um ficheiro ou a um código base64) |
customer_id | O seu ID de utilizador final, com um máximo de 128 caracteres. Utilizado na eliminação de clientes |
metadata | Um objeto JSON com um tamanho máximo de 2 KB, devolvido sem alterações na tarefa e nos webhooks |
webhook_url | URL pública https para receber generation.completed ou generation.failed |
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
{
"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:
curl https://www.tryoncloud.com/api/v1/results/RESULT_ID -H "X-API-KEY: $TRYONCLOUD_API_KEY" -o result.pngUma 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:
{
"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/:iddevolve o número de itens e cada um deles.DELETE /batches/:idcancela 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.completedassim que todos os itens tiverem um resultado.
Webhooks
Enviamos um JSON via POST para o seu webhook_url:
{
"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>:
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).
{ "object": "customer_deletion", "customer_id": "shopper_123", "results_deleted": 3, "records_cleared": 4 }Limites
| Criação de tarefas e lotes | Conta para o limite de 300 pedidos por minuto por chave |
| Tarefas assíncronas a serem executadas simultaneamente | 50 por conta (429 TOO_MANY_JOBS); os lotes são separados |
| Tamanho do lote | 500 artigos |
| Resultados | Guardado durante 7 dias |
| Metadados | Objeto JSON, 2 KB |