# مساحات كنقاط نهاية للواجهات البرمجية

كل مساحة Gradio على Hugging Face متاحة تلقائيًا كنقطة نهاية API. يمكنك استدعاؤها من Python أو JavaScript أو أي عميل HTTP. إذا كان بإمكانك استخدام مساحة في متصفحك، فيمكنك استدعاؤها كـ API.

## البدء السريع

قم بتثبيت عميل Python واستدعاء أي مساحة عامة:

```bash
pip install --upgrade gradio_client
```

```python
from gradio_client import Client

client = Client("abidlabs/en2fr", token="hf_...")
result = client.predict("Hello, world!", api_name="/predict")
print(result)  # "Bonjour, le monde!"
```

## عرض نقاط النهاية المتاحة للواجهة البرمجية

تحتوي كل مساحة Gradio على رابط "استخدام عبر واجهة برمجة التطبيقات" في التذييل. انقر عليه لعرض:

- جميع نقاط النهاية المتاحة وأسمائها
- أنواع المعاملات ووصفاتها
- مقاطع أكواد مولّدة تلقائيًا بلغة بايثون وجافاسكربت
- سجّال واجهة برمجة التطبيقات الذي يولّد الشيفرة من تفاعلاتك مع الواجهة

تعرض كل مساحة أيضًا مواصفة OpenAPI على:

```
https://<space-subdomain>.hf.space/gradio_api/openapi.json
```

على سبيل المثال: `https://abidlabs-en2fr.hf.space/gradio_api/openapi.json`

يُفيد هذا في فهم مخطط واجهة برمجة التطبيقات بالكامل وتكامله في تطبيقاتك الخاصة.

يمكنك أيضًا فحص نقاط النهاية برمجياً:

```python
from gradio_client import Client

client = Client("abidlabs/whisper", token="hf_...")
client.view_api()  # Prints all endpoints with parameters
```

## عميل Python

### التثبيت

```bash
pip install --upgrade gradio_client
```

يتطلب Python 3.10 أو أحدث.

### الاتصال بمساحة

```python
from gradio_client import Client

# Public Space
client = Client("username/space-name")

# Private Space (requires token)
client = Client("username/private-space", token="hf_xxxxx")
```

> [!TIP]
> احصل على رمز Hugging Face الخاص بك من [https://huggingface.co/settings/tokens](https://huggingface.co/settings/tokens). بالنسبة إلى مساحات خاصة، تحتاج إلى رمز يتمتع بصلاحيات **READ**.

### إنشاء تنبؤات

**مزامنة (حاصرة):**

```python
result = client.predict("Hello", api_name="/predict")
```

**غير متزامن (غير حاسم):**

```python
job = client.submit("Hello", api_name="/predict")
# Do other work...
result = job.result()  # Get result when ready
```

### التعامل مع الملفات

استخدم `handle_file()` لأي مدخلات ملفات:

```python
from gradio_client import Client, handle_file

client = Client("abidlabs/whisper", token="hf_...")

# From local file
result = client.predict(audio=handle_file("audio.wav"), api_name="/predict")

# From URL
result = client.predict(audio=handle_file("https://example.com/audio.wav"), api_name="/predict")
```

### مراقبة حالة المهمة

```python
job = client.submit("Hello", api_name="/predict")

# Check status
status = job.status()
print(f"Queue position: {status.rank}, ETA: {status.eta}")

# Check if complete
if job.done():
    result = job.result()

# Cancel a pending job
job.cancel()
```

### نقاط النهاية للبث/المولّد

بالنسبة إلى نقاط النهاية التي تُنتج مخرجات متعددة:

```python
job = client.submit(prompt="Write a story", api_name="/generate")

# Iterate over streaming outputs
for output in job:
    print(output)
```

## عميل JavaScript

### التثبيت

```bash
npm i @gradio/client
```

أو استخدم عبر CDN:

```html
<script type="module">
  import { Client } from "https://cdn.jsdelivr.net/npm/@gradio/client/dist/index.min.js";
</script>
```

### الاتصال والتنبؤ

```javascript
import { Client } from "@gradio/client";

const app = await Client.connect("abidlabs/en2fr", { token: "hf_..." });
const result = await app.predict("/predict", ["Hello"]);
console.log(result.data);
```

### التعامل مع الملفات

```javascript
import { Client, handle_file } from "@gradio/client";

const app = await Client.connect("abidlabs/whisper", { token: "hf_..." });
const result = await app.predict("/predict", [
  handle_file("https://example.com/audio.wav")
]);
```

### بث النتائج

```javascript
const job = app.submit("/predict", ["Hello"]);

for await (const message of job) {
  if (message.type === "data") {
    console.log("Result:", message.data);
  }
  if (message.type === "status") {
    console.log("Queue position:", message.position);
  }
}
```

## واجهة برمجة التطبيقات REST (curl)

يمكنك أيضًا استدعاء Gradio Spaces مباشرة عبر HTTP دون الحاجة إلى أي مكتبة عميل.

### واجهة برمجة التطبيقات القائمة على الطابور (موصى بها)

تعتمد معظم المساحات على عملية من خطوتين:

**الخطوة 1: إرسال طلبك**

```bash
curl -X POST "https://abidlabs-en2fr.hf.space/gradio_api/call/predict" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HF_TOKEN" \
  -d '{"data": ["Hello, world"]}'
```

الاستجابة:
```json
{"event_id": "abc123"}
```

**الخطوة 2: الحصول على النتيجة**

```bash
curl -N "https://abidlabs-en2fr.hf.space/gradio_api/call/predict/abc123" \
  -H "Authorization: Bearer $HF_TOKEN"
```

Response (أحداث يرسلها الخادم):
```
event: complete
data: ["Bonjour, le monde!"]
```

يُعد ترويسة `Authorization` إلزامية للمساحات الخاصة، كما تمنح حدود معدل استخدام أفضل للمساحات العامة.

## مساحات ZeroGPU

تخضع مساحات ZeroGPU لحصص استخدام تعتمد على نوع حسابك:

| نوع الحساب | حصة GPU اليومية المضمنة |
|-------------|--------------------------|
| غير مصادق | دقيقتان |
| حساب مجاني | 5 دقائق |
| حساب PRO | 40 دقيقة |

عندما تُوثّق باستخدام رمزك، يتم استهلاك حصة وحدات المعالجة الرسومية (GPU) الخاصة بحسابك. أما الطلبات غير الموثّقة فتستخدم مجمّعًا مشتركًا يخضع لقيود أكثر صرامة.

يمكن للمستخدمين من فئات PRO وTeam وEnterprise تجاوز الحصة اليومية المضمنة لديهم باستخدام الرصيد المسبق الدفع بمعدل **1 دولار مقابل 10 دقائق** من وقت وحدة المعالجة الرسومية (GPU).

> [!TIP]
> يمكنك [الاشتراك في PRO](https://huggingface.co/subscribe/pro) للحصول على حصة يومية من وحدة معالجة الرسوميات (GPU) لمدة 40 دقيقة، وأولوية أعلى في قائمة الانتظار، وإمكانية توسيع حصتك باستخدام الرصيد.

## أنماط شائعة

### تكامل FastAPI

```python
from fastapi import FastAPI
from gradio_client import Client, handle_file

app = FastAPI()
client = Client("abidlabs/whisper", token="hf_...")

@app.post("/transcribe/")
async def transcribe(file_url: str):
    result = client.predict(audio=handle_file(file_url), api_name="/predict")
    return {"transcription": result}
```

### معالجة الأخطاء مع إعادة المحاولة

```python
import time
from gradio_client import Client

def predict_with_retry(client, *args, max_retries=3, **kwargs):
    for attempt in range(max_retries):
        try:
            return client.predict(*args, **kwargs)
        except Exception as e:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # Exponential backoff
            else:
                raise

client = Client("username/space", token="hf_...")
result = predict_with_retry(client, "input", api_name="/predict")
```

### استدعاء مساحات من مساحة أخرى

عند استدعاء مساحة ZeroGPU من تطبيق Gradio الخاص بك، قم بتحويل مصادقة المستخدم:

```python
import gradio as gr
from gradio_client import Client

def process(prompt, request: gr.Request):
    x_ip_token = request.headers.get('x-ip-token', '')
    client = Client("owner/zerogpu-space", headers={"x-ip-token": x_ip_token})
    return client.predict(prompt, api_name="/predict")

demo = gr.Interface(fn=process, inputs="text", outputs="text")
demo.launch()
```

## العثور على مساحات (Spaces) عبر البحث الدلالي

مع وجود آلاف من مساحات Gradio المتاحة، قد ترغب أحيانًا في العثور على مساحة لمهمة معينة:

```bash
curl -s "https://huggingface.co/api/spaces/semantic-search?q=text+to+speech&sdk=gradio"
```

يعيد هذا الأمر قائمة بـ Spaces مرتبة حسب الصلة الدلالية، مع بيانات وصفية تشمل معرّف Space، وعدد الإعجابات، ووصفًا مختصرًا. استخدم معامل `sdk=gradio` لتصفية Spaces التي تعرض واجهة برمجة تطبيقات (API).

## اعرف المزيد

- [دليل عميل Gradio بلغة بايثون](https://www.gradio.app/guides/getting-started-with-the-python-client)
- [دليل عميل جراسيو جافاسكربت](https://www.gradio.app/guides/getting-started-with-the-js-client)
- [استعلام تطبيقات Gradio باستخدام curl](https://www.gradio.app/guides/querying-gradio-apps-with-curl)
- [مساحات ZeroGPU](./spaces-zerogpu)