# 文件

接受图像、视频或音频的模型支持三种形式。每个模型页面都会标记其文件参数（例如 `image`、`images`、`videos`、`audios`）。

## 1. 公共 URL

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

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

文件必须无需 Cookie 或登录即可访问，并且在请求启动前保持可访问。每个模型页面都会列出其文件参数的大小和尺寸限制。

## 2. Data URI

小文件可以以内联 `data:` URI 的形式传入，大小最多为 10 MB：

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

Base64 会使请求体比文件大约增加三分之一，因此较大文件应优先使用上传。

## 3. 上传

对于本地文件，请获取上传 URL，使用 `PUT` 将字节上传到该 URL，然后将返回的 `file_url` 传给模型。创建上传 URL 是免费的。

```bash 1 · 获取上传 URL
curl -X POST "https://api.doitong.ru/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.ru/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 有效期为 1 小时。`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.ru/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 天充值，之后保留的文件会变为临时文件。