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ítulo | Valor |
|---|---|
X-API-KEY | A sua chave, tk_dev_v1_... (obrigatória) |
X-Mock | true para o modo de teste gratuito (opcional, equivalente a ?mock=true) |
Idempotency-Key | Opcional. 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.
| Campo | Tipo | Descrição |
|---|---|---|
garment_image | ficheiro | A foto da peça de roupa. Ou utilize garment_url ou garment_base64 |
garment_url | cadeia de caracteres | Um URL público de imagem https. Fazemos o download do lado do servidor |
garment_base64 | cadeia de caracteres | Imagem em Base64, com ou sem o prefixo data: |
person_image | ficheiro | A fotografia do cliente. Ou utilize person_base64 |
person_base64 | cadeia de caracteres | Imagem em Base64, com ou sem o prefixo data: |
customer_id | cadeia de caracteres | Opcional. 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âmetro | Descrição |
|---|---|
mock=true | Modo 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 resposta | Significado |
|---|---|
X-Request-Id | Identificador ú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-Remaining | O seu limite por minuto e o tempo restante neste minuto |
X-Credit-Was-Free | 1 se esta experimentação utilizou a tua quota gratuita, 0 se utilizou créditos adquiridos |
X-Result-Id | Apenas quando o armazenamento de resultados estiver ativado na sua conta. Utilize esta funcionalidade em conjunto com a opção Eliminar um resultado |
X-Mock | 1 nas respostas do modo de teste |
X-Costume | Apenas 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 acontece | Resposta |
|---|---|
| Primeiro pedido | Funciona normalmente |
| Tentar novamente enquanto a primeira ainda estiver a ser executada | 409 IDEMPOTENCY_IN_PROGRESS com Retry-After, sem cobrança |
| Tentar novamente depois de ter sido bem-sucedido | 409 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 falha | Vai realizar-se novamente (a tentativa falhada foi reembolsada) |
| A mesma chave, imagens diferentes | 409 IDEMPOTENCY_MISMATCH |
Sem o cabeçalho, cada pedido é uma nova tentativa.
Exemplos
em várias partes (ficheiros)
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.pngJSON (URL da peça de roupa + pessoa em base64)
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.pngNode.js, versão 18 ou superior
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_REACHEDaté 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.