# الملفات

تقبل النماذج التي تتعامل مع الصور أو الفيديو أو الصوت هذه الملفات بأي صيغة من ثلاث. وتحدد صفحة كل نموذج معلمات ملفاته (مثل `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`. ويمكنك تمريرها مباشرةً إلى نموذج آخر، مثل صورة من نموذج تحويل النص إلى صورة إلى نموذج تحويل الصورة إلى فيديو.

تختار مدة الاحتفاظ بملفات المخرج:

- **إلى الأبد** (`permanent`، الافتراضي): حتى تحذفها، مقابل 100 أرصدة API (⁨‏0.10 $⁩) لكل GB شهريًا، تُفرض مرة يوميًا من رصيد API (1 GB = 1024³ bytes).
- **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 يومًا لشحن الرصيد قبل أن تصبح الملفات المحتفظ بها مؤقتة.