# فایل‌ها

مدل‌هایی که تصویر، ویدیو یا صوت می‌گیرند، آن‌ها را در هر یک از سه شکل می‌پذیرند. صفحه هر مدل پارامترهای فایل آن (مثلاً `image`، `images`، `videos`، `audios`) را مشخص می‌کند.

## 1. یک URL عمومی

هر URL از نوع `https://` (یا `http://`) که مدل بتواند بارگیری کند:

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

فایل باید بدون کوکی یا ورود قابل دسترسی باشد و تا شروع درخواست قابل دسترسی بماند. صفحه هر مدل محدودیت‌های اندازه و ابعاد پارامترهای فایل آن را فهرست می‌کند.

## 2. یک URI داده

فایل‌های کوچک می‌توانند به‌صورت یک URI از نوع `data:` با حداکثر 10 MB درون‌خطی ارسال شوند:

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

Base64 بدنه را حدود یک‌سوم بزرگ‌تر از فایل می‌کند؛ بنابراین برای موارد بزرگ، بارگذاری را ترجیح دهید.

## 3. یک بارگذاری

برای فایل‌های محلی، یک URL بارگذاری بگیرید، بایت‌ها را با `PUT` در آن قرار دهید و `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 عمومی یا URI داده استفاده کنید.

## فایل‌های خروجی

> [!TIP]
> فایل‌های تولیدشده در فضای ذخیره‌سازی ما کپی و در `outputs[].url` به‌صورت پیوندهایی روی `content.doitong.com` برگردانده می‌شوند. می‌توانید آن‌ها را مستقیماً به مدل دیگری بدهید؛ مثلاً تصویر یک مدل text-to-image را به مدل image-to-video.

مدت نگهداری فایل‌های خروجی را شما انتخاب می‌کنید:

- **برای همیشه** (`permanent`، پیش‌فرض): تا زمان حذف، با ۱۰۰ اعتبار API (⁨‎$۰٫۱۰⁩) برای هر GB در ماه، با کسر روزانه از موجودی API (1 GB = 1024³ بایت).
- **۷ روز** (`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 نتواند هزینه فضای ذخیره‌سازی را پرداخت کند، ایمیلی دریافت می‌کنید و ۳۰ روز برای افزایش موجودی فرصت دارید، پیش از آنکه فایل‌های نگهداری‌شده موقت شوند.