Search docs

Search the TryOnCloud API docs

Referência da API

Gerar uma simulação de prova

POST /api/v1/generate: entrada de peça de vestuário + pessoa, saída de ficheiro PNG finalizado.

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 https://www.tryoncloud.com/api/v1/generate

Envie uma peça de roupa e uma pessoa e receba a imagem da prova final como resposta. Um pedido, uma imagem, sem sondagens.

Cabeçalhos

TítuloValor
X-API-KEYA sua chave, tk_dev_v1_... (obrigatória)
X-Mocktrue para o modo de teste gratuito (opcional, equivalente a ?mock=true)
Idempotency-KeyOpcional. O seu próprio valor único por tentativa (1 a 255 caracteres imprimíveis). Uma nova tentativa com a mesma chave nunca é cobrada duas vezes. Ver Novas tentativas e idempotência

Corpo

Envie multipart/form-data ou application/json. São necessárias duas imagens.

CampoTipoDescrição
garment_imageficheiroA foto da peça de roupa. Ou utilize garment_url ou garment_base64
garment_urlcadeia de caracteresUm URL público de imagem https. Fazemos o download do lado do servidor
garment_base64cadeia de caracteresImagem em Base64, com ou sem o prefixo data:
person_imageficheiroA fotografia do cliente. Ou utilize person_base64
person_base64cadeia de caracteresImagem em Base64, com ou sem o prefixo data:
customer_idcadeia de caracteresOpcional. A sua própria identificação para o utilizador final, com um máximo de 128 caracteres. Procure-a no painel de controlo e apague os dados desse utilizador através da opção Apagar os dados de um cliente.

As imagens têm de estar nos formatos JPEG, PNG, WebP ou HEIC, com um tamanho máximo de 15 MB cada. É verificado o conteúdo do ficheiro, e não apenas o nome ou o tipo declarado.

Parâmetros de consulta

ParâmetroDescrição
mock=trueModo de teste: valida tudo, não gera nada, não cobra nada, não armazena nada. Devolve a imagem da pessoa sem alterações

Resposta

200 OK. O corpo da resposta é a imagem final, Content-Type: image/png, com cerca de 1 megapixel (da classe «1K»). Leia-a como bytes; não a analise como JSON.

Cabeçalho da respostaSignificado
X-Request-IdIdentificador único deste pedido, presente em todas as respostas, incluindo as que contêm erros. Indique-o ao apoio técnico
X-RateLimit-Limit / X-RateLimit-RemainingO seu limite por minuto e o tempo restante neste minuto
X-Credit-Was-Free1 se esta experimentação utilizou a tua quota gratuita, 0 se utilizou créditos adquiridos
X-Result-IdApenas quando o armazenamento de resultados estiver ativado na sua conta. Utilize esta funcionalidade em conjunto com a opção Eliminar um resultado
X-Mock1 nas respostas do modo de teste
X-CostumeApenas para contas com o modo «costume» ativado

Os erros devolvem um JSON { "error": "...", "code": "..." }. Consulte a secção Erros.

Novas tentativas e idempotência

As redes interrompem as ligações. Para voltar a tentar com segurança, envie um cabeçalho Idempotency-Key com um valor gerado para cada tentativa (por exemplo, um UUID) e reutilize-o apenas para novas tentativas dessa mesma tentativa. As chaves são mantidas durante 24 horas por chave de API.

O que aconteceResposta
Primeiro pedidoFunciona normalmente
Tentar novamente enquanto a primeira ainda estiver a ser executada409 IDEMPOTENCY_IN_PROGRESS com Retry-After, sem cobrança
Tentar novamente depois de ter sido bem-sucedido409 IDEMPOTENCY_REPLAY, sem custos. A imagem constava na primeira resposta; com o armazenamento de resultados ativado, o result_id identifica-a
Tentar novamente após a falhaVai realizar-se novamente (a tentativa falhada foi reembolsada)
A mesma chave, imagens diferentes409 IDEMPOTENCY_MISMATCH

Sem o cabeçalho, cada pedido é uma nova tentativa.

Exemplos

em várias partes (ficheiros)

bash
curl -X POST https://www.tryoncloud.com/api/v1/generate \
  -H "X-API-KEY: $TRYONCLOUD_API_KEY" \
  -F "garment_image=@shirt.jpg" \
  -F "person_image=@person.jpg" \
  -o result.png

JSON (URL da peça de roupa + pessoa em base64)

bash
curl -X POST https://www.tryoncloud.com/api/v1/generate \
  -H "X-API-KEY: $TRYONCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"garment_url\":\"https://cdn.yourstore.com/shirt.jpg\",\"person_base64\":\"$(base64 -w0 person.jpg)\"}" \
  -o result.png

Node.js, versão 18 ou superior

js
import { readFile, writeFile } from "node:fs/promises"

const form = new FormData()
form.append("garment_image", new Blob([await readFile("shirt.jpg")]), "shirt.jpg")
form.append("person_image", new Blob([await readFile("person.jpg")]), "person.jpg")

const res = await fetch("https://www.tryoncloud.com/api/v1/generate", {
  method: "POST",
  headers: { "X-API-KEY": process.env.TRYONCLOUD_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
})
if (!res.ok) {
  const { error, code } = await res.json()
  throw new Error(`${code}: ${error}`)
}
await writeFile("result.png", Buffer.from(await res.arrayBuffer()))

Faturação

  • Se a chave da API tiver um limite de crédito mensal e este for atingido, o pedido é recusado com o código de erro 402 KEY_LIMIT_REACHED até ao dia 1 (UTC). Defina os limites ao criar uma chave na página Chaves da API.
  • Cada experimentação bem-sucedida consome um crédito.
  • As gerações com falha (422, 500) são reembolsadas automaticamente.
  • O modo de teste é sempre gratuito.
  • As contas que compraram créditos gastam os créditos adquiridos. As contas que não o fizeram gastam a quota gratuita.