> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-de47a659.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

> حسِّن دقّة الفيديو وجودته بنموذج topaz-video-upscale على طابور الفيديو غير المتزامن في Venice، مع معاملات تكبير بمقدار 1x أو 2x أو 4x.

تتيح لك ترقية دقّة الفيديو تحسين مقاطع الفيديو الحالية إلى دقّات أعلى مع تحسين الجودة البصرية. يستخدم نموذج **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={null}
  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={null}
  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={null}
  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={null}
{
  "model": "topaz-video-upscale",
  "queue_id": "abc123-def456-..."
}
```

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

<CodeGroup>
  ```bash cURL theme={null}
  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={null}
  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={null}
  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={null}
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={null}
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",
    "video_url": "https://example.com/input.mp4"
  }'
```

`video_url` **مطلوب** لعروض الأسعار على نماذج رفع الدقة — تجلب نقطة نهاية الاقتباس الملف وتكتشف المدة ومعدل الإطارات والارتفاع من البايتات، فلا حاجة لتزويدها. حذفه يعيد `400` مع *"video\_url is required for quotes on this model"*.

<Warning>
  تسمّي نقطتا نهاية الاقتباس والطابور مُعامل رفع الدقة باسمين مختلفين حاليًا: يأخذ `/video/queue` المعامل `upscale_factor` (`1` أو `2` أو `4`)، بينما يقرأ `/video/quote` المُعامل من `resolution` (`"2x"` أو `"4x"`). إرسال `upscale_factor` إلى نقطة نهاية الاقتباس لا تأثير له — إذ تعود إلى القيمة الافتراضية `"2x"` وتعيد سعر 2x لما قد يكون مهمة 4x. عند طلب عرض سعر لرفع دقة 4x، مرّر `resolution: "4x"`.
</Warning>

***

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

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