> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 檔案上傳

> 把圖片、影片或聲音檔交給工作。

媒體輸入可以是以下兩種值：

| 值 | 適用情境 |
| - | - |
| `{ "url": "https://…" }` | 檔案已在公開網址上。Blon 會先匯入，再估價。 |
| `{ "asset_id": "…" }` | 檔案已在 Blon：上傳的檔案，或先前工作的產物。 |

## 從網址匯入

把網址放進輸入即可。提交或估價時 Blon 會抓取（60 秒內）；抓不到、超過大小上限或無法讀取時回 `422 input_media_unreadable`。

```json theme={null}
{
  "model": "seedance-2.0",
  "input": {
    "prompt": "Slow push-in",
    "firstFrame": { "url": "https://example.com/frame.png" }
  }
}
```

## 上傳本機檔案

上傳分三個請求。Blon 金鑰只送給 Blon，絕不送到上傳網址。

**1. 宣告檔案**

```bash theme={null}
curl https://api.blon.ai/v1/uploads \
  -H "Authorization: Bearer $BLON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content_type":"image/png","size_bytes":1482113,"file_name":"frame.png"}'
```

`201` 回應包含 `upload_url`、`upload_headers`、`ticket` 與其 `expires_at`（10 分鐘）。

**2. 上傳檔案內容**

以 `PUT` 把檔案送到 `upload_url`，並帶上 `upload_headers` 的 header。不要加 `Authorization` header。

```bash theme={null}
curl -X PUT "$UPLOAD_URL" -H "content-type: image/png" --data-binary @frame.png
```

**3. 完成上傳**

```bash theme={null}
curl https://api.blon.ai/v1/uploads/complete \
  -H "Authorization: Bearer $BLON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticket":"…"}'
```

回應包含 `asset_id`、`content_type`、`size_bytes`、`media`（`duration_seconds`、`width`、`height`）與 `expires_at`。同一張票券重複完成會回同一個素材。

接著在工作中使用：`"firstFrame": { "asset_id": "…" }`。

## 上限

| | 上限 |
| - | - |
| 圖片 | 20,000,000 bytes |
| 影片、聲音與其他檔案 | 52,428,800 bytes |
| `file_name` | 200 字元 |

| 錯誤 | 情況 |
| - | - |
| `413 payload_too_large` | 宣告的 `size_bytes` 超過上限 |
| `415 unsupported_media_type` | 不支援此 `content_type` |
| `401 unauthorized` | 票券無效或已過期 |
| `422 input_media_unreadable` | 檔案未上傳、與票券不符或無法讀取 |

## 保存期限

透過 API 上傳或匯入的檔案，以及 API 建立的產物，7 天後到期（`expires_at`）。在 Blon 站內加入素材庫的檔案則會保留。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.