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

# ترقية دقّة الفيديو (Upscaling)

> حسِّن دقّة الفيديو وجودته على Venice API باستخدام نموذج Topaz Video Upscale — أرسل مقطعًا مصدريًا، اختر مقياسًا، واسترجع النتيجة.

تتيح لك ترقية دقّة الفيديو تحسين مقاطع الفيديو الحالية إلى دقّات أعلى مع تحسين الجودة البصرية. يستخدم نموذج **Topaz Video Upscale** ترقيةً مدفوعة بالذكاء الاصطناعي لرفع الدقّة بمعامل 2x أو 4x، أو لتطبيق تحسين جودة بنفس الدقّة الأصلية (1x).

## كيف يعمل

تستخدم ترقية الفيديو نفس نظام الطابور غير المتزامن المستخدم في توليد الفيديو:

1. **Queue** — أرسل فيديوك إلى `/video/queue` مع النموذج `topaz-video-upscale`
2. **Poll** — تحقّق عبر `/video/retrieve` باستخدام `queue_id` المُعاد حتى تصبح الحالة `completed`
3. **Complete** — استدعِ `/video/complete` لإنهاء المهمة والحصول على رابط الإخراج

يكتشف الخادم تلقائيًا مدة فيديو الإدخال ومعدل إطاراته وأبعاده من الملف المرفوع. لا تحتاج إلى تقديم هذه القيم — إذ تُحتسب الفوترة من بيانات الفيديو الفعلية.

## معاملات الترقية

| `upscale_factor` | دقّة الإخراج      | حالة الاستخدام                             |
| ---------------- | ----------------- | ------------------------------------------ |
| `1`              | نفس الإدخال       | تحسين جودة فقط (إزالة ضوضاء، تحسين الحدّة) |
| `2` (افتراضي)    | أبعاد الإدخال × 2 | ترقية قياسية — إدخال 720p يصبح إخراج 1440p |
| `4`              | أبعاد الإدخال × 4 | ترقية قصوى — إدخال 480p يصبح إخراج 1920p   |

<Note>
  معامل `upscale_factor` يحل محل `resolution` لنماذج الترقية. تمرير `resolution` سيُعيد خطأ. وذلك لأن دقّة الإخراج تعتمد على أبعاد فيديو الإدخال — فترقية `2x` لفيديو 720p تنتج نتيجة مختلفة عن ترقية `2x` لفيديو 480p.
</Note>

## صيغ الإدخال المدعومة

* **الصيغ**: MP4، MOV، WebM
* **طرق الإدخال**: رابط HTTPS أو رابط بيانات `data:video/...;base64,...`
* **أقصى مدة**: 300 ثانية (5 دقائق)

## استخدام API

### إرسال مهمة ترقية إلى الطابور

<CodeGroup>
  ```bash cURL theme={"system"}
  curl https://api.venice.ai/api/v1/video/queue \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "topaz-video-upscale",
      "video_url": "https://example.com/input-video.mp4",
      "upscale_factor": 2
    }'
  ```

  ```python Python theme={"system"}
  import requests

  response = requests.post(
      "https://api.venice.ai/api/v1/video/queue",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={
          "model": "topaz-video-upscale",
          "video_url": "https://example.com/input-video.mp4",
          "upscale_factor": 2,
      },
  )

  data = response.json()
  queue_id = data["queue_id"]
  print(f"Queued: {queue_id}")
  ```

  ```javascript Node.js theme={"system"}
  const response = await fetch("https://api.venice.ai/api/v1/video/queue", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "topaz-video-upscale",
      video_url: "https://example.com/input-video.mp4",
      upscale_factor: 2,
    }),
  });

  const { queue_id } = await response.json();
  console.log(`Queued: ${queue_id}`);
  ```
</CodeGroup>

تتضمن الاستجابة `queue_id` لتتبّع المهمة:

```json theme={"system"}
{
  "model": "topaz-video-upscale",
  "queue_id": "abc123-def456-..."
}
```

### الاستعلام عن الاكتمال

<CodeGroup>
  ```bash cURL theme={"system"}
  curl https://api.venice.ai/api/v1/video/retrieve \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"queue_id": "abc123-def456-..."}'
  ```

  ```python Python theme={"system"}
  import time

  while True:
      result = requests.post(
          "https://api.venice.ai/api/v1/video/retrieve",
          headers={"Authorization": "Bearer YOUR_API_KEY"},
          json={"queue_id": queue_id},
      )
      data = result.json()

      if data.get("status") == "completed":
          print(f"Video URL: {data['url']}")
          break

      time.sleep(5)
  ```

  ```javascript Node.js theme={"system"}
  const poll = async (queueId) => {
    while (true) {
      const res = await fetch("https://api.venice.ai/api/v1/video/retrieve", {
        method: "POST",
        headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ queue_id: queueId }),
      });
      const data = await res.json();

      if (data.status === "completed") {
        console.log(`Video URL: ${data.url}`);
        return data;
      }

      await new Promise((r) => setTimeout(r, 5000));
    }
  };

  await poll(queue_id);
  ```
</CodeGroup>

### الإنهاء بـ complete

بعد استرجاع النتيجة، استدعِ `/video/complete` للإنهاء:

```bash theme={"system"}
curl https://api.venice.ai/api/v1/video/complete \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue_id": "abc123-def456-..."}'
```

***

## معاملات API

| الحقل            | النوع  | مطلوب   | الوصف                                                              |
| ---------------- | ------ | ------- | ------------------------------------------------------------------ |
| `model`          | string | **نعم** | يجب أن يكون `topaz-video-upscale`                                  |
| `video_url`      | string | **نعم** | رابط فيديو الإدخال أو رابط بيانات. الصيغ المدعومة: MP4، MOV، WebM. |
| `upscale_factor` | number | لا      | `1` أو `2` (افتراضي) أو `4`. يتحكم في مُضاعف الترقية.              |

### معاملات لا تُستخدم لنماذج الترقية

المعاملات التالية **لا تُقبل** لـ `topaz-video-upscale` وستُعيد خطأ إذا قُدِّمت:

| الحقل        | السبب                                                                    |
| ------------ | ------------------------------------------------------------------------ |
| `resolution` | استخدم `upscale_factor` بدلًا منه. دقّة الإخراج تعتمد على أبعاد الإدخال. |
| `prompt`     | الترقية لا تستخدم تعليمات نصية. تُعيَّن سلسلة فارغة تلقائيًا.            |

كذلك يُتجاهل معامل `duration` — إذ يكتشف الخادم المدة مباشرة من ملف الفيديو لأجل دقّة الفوترة.

***

## التسعير

يستند التسعير إلى **المدة** و**فئة دقّة الإخراج** و**معدل الإطارات**. تُحدَّد فئة دقّة الإخراج بضرب ارتفاع فيديو الإدخال في معامل الترقية.

### فئات دقّة الإخراج

| الفئة | ارتفاع الإخراج | السعر لكل ثانية |
| ----- | -------------- | --------------- |
| 720p  | ≤ 720 بكسل     | \~\$0.013       |
| 1080p | 721–1080 بكسل  | \~\$0.025       |
| 4K    | > 1080 بكسل    | \~\$0.10        |

<Note>
  مقاطع الفيديو بمعدلات إطارات أعلى من 48fps تكلّف ضعف السعر لكل ثانية.
</Note>

### أمثلة تسعير

| الإدخال      | معامل الترقية | الإخراج          | المدة | التكلفة التقديرية |
| ------------ | ------------- | ---------------- | ----- | ----------------- |
| 480p، 30fps  | 2x            | 960p (فئة 1080p) | 10 ث  | \~\$0.25          |
| 720p، 30fps  | 2x            | 1440p (فئة 4K)   | 10 ث  | \~\$1.00          |
| 1080p، 30fps | 2x            | 2160p (فئة 4K)   | 30 ث  | \~\$3.00          |
| 360p، 24fps  | 4x            | 1440p (فئة 4K)   | 10 ث  | \~\$1.00          |
| 480p، 60fps  | 2x            | 960p (فئة 1080p) | 10 ث  | \~\$0.50          |

استخدم [Video Quote API](/api-reference/endpoint/video/quote) للحصول على التسعير الدقيق قبل إرسال المهمة.

### الحصول على عرض سعر

```bash theme={"system"}
curl https://api.venice.ai/api/v1/video/quote \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "topaz-video-upscale",
    "duration": "10",
    "input_height": 720
  }'
```

تقبل نقطة نهاية الاقتباس `input_height` لتقدير فئة دقّة الإخراج. هذا اختياري — إذا حُذف، يفترض الاقتباس تقديرًا متحفظًا.

***

## استكشاف الأخطاء وإصلاحها

| المشكلة                                      | السبب المرجّح                                 | الإصلاح                                                                                          |
| -------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `"Use upscale_factor instead of resolution"` | تم تمرير `resolution` في الطلب                | أزِل `resolution` واستخدم `upscale_factor` بدلًا منه                                             |
| تكلفة أعلى من المتوقع                        | فيديو الإدخال بدقّة عالية أو معدل إطارات عالٍ | تحقّق من أبعاد الإدخال عبر نقطة نهاية الاقتباس. إدخال 720p+ مع ترقية 2x يقع في فئة تسعير 4K.     |
| تستغرق المهمة وقتًا طويلًا                   | فيديو كبير أو طويل                            | الترقية مكثّفة حسابيًا. مقاطع الفيديو الأطول ومعاملات الترقية الأعلى تستغرق وقتًا أطول تناسبيًا. |
| `"Insufficient balance"`                     | أرصدة الحساب منخفضة جدًا                      | أضف رصيدًا من [venice.ai/settings/api](https://venice.ai/settings/api)                           |