# Gerar uma simulação de prova

`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](#retries-and-idempotency) |

## 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.](/docs/async#delete-a-customers-data) |

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](/docs/delete-result) |
| `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](/docs/errors).

## 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)

```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.
