# 檔案

接受圖像、影片或音訊的模型支援三種形式。每個模型頁面都會標示其檔案參數（例如 `image`、`images`、`videos`、`audios`）。

## 1. 公開 URL

模型可以下載的任何 `https://`（或 `http://`）URL：

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

檔案必須能在沒有 Cookie 或登入的情況下存取，並持續可存取到請求開始為止。每個模型頁面都會列出其檔案參數的大小及尺寸限制。

## 2. Data URI

小型檔案可以內嵌為最大 10 MB 的 `data:` URI：

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

Base64 會使本文體比檔案大約增加三分之一，因此大型檔案請優先使用上傳。

## 3. 上傳

對於本機檔案，先取得上傳 URL，將位元組以 `PUT` 傳送到該 URL，再將回傳的 `file_url` 傳給模型。建立上傳 URL 不收費。

```bash 1 · 取得上傳 URL
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 · 上傳
{
  "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 · 使用完全相同的回傳標頭上傳位元組
curl -X PUT "<upload_url>" -H "Content-Type: image/jpeg" --data-binary @product.jpg
```

```bash 3 · 使用 file_url 作為模型輸入
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": "..."}'
```

- 支援的上傳格式：`.jpg`、`.jpeg`、`.png`、`.webp`（最多 15 MB）以及 `.mp4`、`.mov`、`.webm`（最多 200 MB）。副檔名會設定類型；`content_type` 必須與其相符。
- 上傳 URL 的有效期限為一小時。`file_url` 會持續有效。
- 對於音訊，請使用公開 URL 或 data URI。

## 輸出檔案

> [!TIP]
> 產生的檔案會複製到我們的儲存空間，並以 `outputs[].url` 的形式回傳 `content.doitong.com` 上的連結。你可以直接將這些連結傳入另一個模型，例如將文字生成圖像模型的圖像傳入圖像生成影片模型。

你可以選擇輸出檔案的保留時間：

- **永久**（`permanent`，預設值）：直到你刪除檔案為止，每 GB 每月 100 API 點數（$0.10），每日從 API 餘額扣款（1 GB = 1024³ 位元組）。
- **7 天**（`temporary`）：免費，之後會從我們的儲存空間刪除。

在[控制台](https://doitong.com/developers/dashboard#balance)中使用「永久保存檔案」切換開關，或使用 `PATCH /account/storage` 設定預設值；也可以透過 `?storage=temporary`（或 `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"}'
```

每個請求都會顯示自己的 `storage`（`mode`、`bytes`、`expires_at`、`expired`）。設定只會套用至新請求；你已永久保留的檔案會持續存在，直到你使用 `DELETE /requests/{id}/files` 刪除（請參閱[請求](https://doitong.com/developers/docs/requests#delete-files)）。如果 API 餘額無法支付儲存費用，你會收到電子郵件，並有 30 天可以儲值，之後保留的檔案會變為暫存檔案。