# Ficheiros

Os modelos que aceitam imagens, vídeo ou áudio permitem-nos em qualquer uma de três formas. Cada página de modelo assinala os seus parâmetros de ficheiro (por exemplo, `image`, `images`, `videos`, `audios`).

## 1. Um URL público

Qualquer URL `https://` (ou `http://`) que o modelo consiga transferir:

```json
{ "image": "https://example.com/photos/product.jpg" }
```

O ficheiro tem de estar acessível sem cookies ou início de sessão e permanecer acessível até o pedido ter começado. Cada página de modelo lista os limites de tamanho e dimensões dos seus parâmetros de ficheiro.

## 2. Um URI de dados

Os ficheiros pequenos podem ser incluídos diretamente como um URI `data:` de até 10 MB:

```json
{ "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." }
```

O Base64 torna o corpo cerca de um terço maior do que o ficheiro, por isso prefira carregamentos para ficheiros grandes.

## 3. Um carregamento

Para ficheiros locais, peça um URL de carregamento, faça `PUT` dos bytes para esse URL e passe o `file_url` devolvido ao modelo. A criação do URL de carregamento é gratuita.

```bash 1 · Obter um URL de carregamento
curl -X POST "https://api.doitong.com/v1/files" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "product.jpg", "content_type": "image/jpeg", "size": 482113}'
```

```json 201 Created · carregamento
{
  "object": "upload",
  "upload_url": "https://…signed upload URL…",
  "file_url": "https://content.doitong.com/…/product.jpg",
  "method": "PUT",
  "headers": { "Content-Type": "image/jpeg" },
  "content_type": "image/jpeg",
  "expires_in": 3600,
  "max_bytes": 15728640
}
```

```bash 2 · Carregar os bytes com exatamente os cabeçalhos devolvidos
curl -X PUT "<upload_url>" -H "Content-Type: image/jpeg" --data-binary @product.jpg
```

```bash 3 · Usar file_url como entrada do modelo
curl -X POST "https://api.doitong.com/v1/run/{model_id}?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image": "https://content.doitong.com/…/product.jpg", "prompt": "..."}'
```

- Carregamentos suportados: `.jpg`, `.jpeg`, `.png`, `.webp` (até 15 MB) e `.mp4`, `.mov`, `.webm` (até 200 MB). A extensão define o tipo; `content_type` tem de corresponder-lhe.
- O URL de carregamento é válido durante uma hora. O `file_url` permanece válido.
- Para áudio, use um URL público ou um URI de dados.

## Ficheiros de saída

> [!TIP]
> Os ficheiros gerados são copiados para o nosso armazenamento e devolvidos em `outputs[].url` como ligações em `content.doitong.com`. Pode passá-los diretamente para outro modelo, por exemplo uma imagem de um modelo de texto para imagem para um modelo de imagem para vídeo.

Escolhe durante quanto tempo os ficheiros de saída são mantidos:

- **Para sempre** (`permanent`, a predefinição): até os eliminar, por 100 créditos de API (0,10 $) por GB por mês, cobrados uma vez por dia ao saldo de API (1 GB = 1024³ bytes).
- **7 dias** (`temporary`): gratuito, sendo depois eliminado do nosso armazenamento.

Defina a predefinição com o interruptor "Guardar ficheiros para sempre" no [dashboard](https://doitong.com/developers/dashboard#balance) ou com `PATCH /account/storage`, e substitua-a por execução com `?storage=temporary` (ou `permanent`):

```bash
curl -X PATCH "https://api.doitong.com/v1/account/storage" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "temporary"}'
```

Cada pedido mostra o seu próprio `storage` (`mode`, `bytes`, `expires_at`, `expired`). A definição aplica-se aos novos pedidos; os ficheiros que já mantém para sempre permanecem até os eliminar com `DELETE /requests/{id}/files` (consulte [Pedidos](https://doitong.com/developers/docs/requests#delete-files)). Se o saldo de API não conseguir pagar o armazenamento, recebe um email e dispõe de 30 dias para fazer um carregamento antes de os ficheiros mantidos passarem a temporários.