كيفية استخدام Qwen3.8-Omni-Flash API
المتطلبات الأساسية
- احتفظ بمفتاح API في متغير البيئة QWEN_API_KEY.
- ثبّت requests وwebsockets وaiohttp أو ما يناسبك عند الحاجة.
- اضبط BASE_URL وMODEL:
- BASE_URL: https://api.qwen.ai/v1
- MODEL: Qwen3.8-Omni-Flash
- احرص على أن تبقى أسماء الحقول/المفاتيح/المعرفات كما هي، ولا تترجمها. تُترجم فقط النصوص المرئية للمستخدم والتعليقات.
1) استخدام Python لنص فقط (Synchronous)
- إرسال طلب نصي بسيط وإرجاع استجابة نصية:
```python
import os
import requests
BASE_URL = "https://api.qwen.ai/v1"
MODEL = "Qwen3.8-Omni-Flash"
API_KEY = os.getenv("QWEN_API_KEY")
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": MODEL,
"input": [
{
"role": "user",
"content": [
{"type": "input_text", "text": "اكتب ملخصاً من 3 جمل عن التعلم الآلي."}
]
}
]
}
resp = requests.post(f"{BASE_URL}/responses", json=payload, headers=headers, timeout=60)
resp.raise_for_status()
data = resp.json()
# نص الاستجابة
print(data.get("output", {}).get("text", ""))
```
2) استخدام cURL لنص فقط
```bash
curl -X POST "$BASE_URL/responses" \
-H "Authorization: Bearer $QWEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "Qwen3.8-Omni-Flash",
"input": [
{ "role": "user", "content": [
{ "type": "input_text", "text": "أعطني 5 أفكار لحملات تسويق قصيرة." }
]}
]
}'
```
3) إدخال صورة (رابط أو ملف)
- عبر رابط صورة:
```python
import os, requests
BASE_URL = "https://api.qwen.ai/v1"
MODEL = "Qwen3.8-Omni-Flash"
API_KEY = os.getenv("QWEN_API_KEY")
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": MODEL,
"input": [
{"role": "user", "content": [
{"type": "input_text", "text": "صف محتوى الصورة بإيجاز."},
{"type": "input_image", "image_url": "https://example.com/photo.jpg"}
]}
]
}
r = requests.post(f"{BASE_URL}/responses", json=payload, headers=headers, timeout=120)
r.raise_for_status()
print(r.json().get("output", {}).get("text", ""))
```
- عبر ملف محلي (base64):
```python
import os, base64, requests
with open("image.png", "rb") as f:
b64 = base64.b64encode(f.read()).decode("utf-8")
payload = {
"model": "Qwen3.8-Omni-Flash",
"input": [
{"role": "user", "content": [
{"type": "input_text", "text": "ما الموجود في هذه الصورة؟"},
{"type": "input_image", "image": {"format": "png", "data": b64}}
]}
]
}
# إرسال كما في المثال السابق
```
4) إدخال صوت (تحويل كلام إلى نص/تحليل صوت)
- مثال: إرسال ملف WAV وفهم محتواه:
```python
import os, base64, requests
BASE_URL = "https://api.qwen.ai/v1"
MODEL = "Qwen3.8-Omni-Flash"
API_KEY = os.getenv("QWEN_API_KEY")
with open("sample.wav", "rb") as f:
audio_b64 = base64.b64encode(f.read()).decode("utf-8")
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": MODEL,
"input": [
{"role": "user", "content": [
{"type": "input_text", "text": "حوّل هذا الصوت إلى نص ثم لخصه بجملة."},
{"type": "input_audio", "audio": {"format": "wav", "data": audio_b64}}
]}
]
}
r = requests.post(f"{BASE_URL}/responses", json=payload, headers=headers, timeout=180)
r.raise_for_status()
print(r.json().get("output", {}).get("text", ""))
```
5) إدخال فيديو (تحليل/وصف)
- مثال: فيديو قصير (MP4) لتحليل المحتوى:
```python
import os, base64, requests
with open("clip.mp4", "rb") as f:
video_b64 = base64.b64encode(f.read()).decode("utf-8")
payload = {
"model": "Qwen3.8-Omni-Flash",
"input": [
{"role": "user", "content": [
{"type": "input_text", "text": "اشرح ما يحدث في الفيديو بإيجاز."},
{"type": "input_video", "video": {"format": "mp4", "data": video_b64}}
]}
]
}
# إرسال كما في الأمثلة السابقة
```
6) إخراج صوت (Text-to-Speech)
- توليد صوت من الاستجابة:
```python
import os, requests, base64
BASE_URL = "https://api.qwen.ai/v1"
MODEL = "Qwen3.8-Omni-Flash"
API_KEY = os.getenv("QWEN_API_KEY")
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": MODEL,
"modalities": ["text", "audio"],
"audio": {"voice": "female_1", "format": "mp3"},
"input": [
{"role": "user", "content": [
{"type": "input_text", "text": "اقرأ لي هذا النص بصوت واضح: مرحباً بكم جميعاً."}
]}
]
}
r = requests.post(f"{BASE_URL}/responses", json=payload, headers=headers, timeout=120)
r.raise_for_status()
out = r.json()
# احصل على الصوت الناتج (base64) واحفظه
audio_b64 = out.get("output", {}).get("audio", {}).get("data")
if audio_b64:
with open("output.mp3", "wb") as f:
f.write(base64.b64decode(audio_b64))
```
7) البثّ (Streaming) عبر Python
- استقبال الاستجابة كسيل أحداث:
```python
import os, sseclient, requests
BASE_URL = "https://api.qwen.ai/v1"
MODEL = "Qwen3.8-Omni-Flash"
API_KEY = os.getenv("QWEN_API_KEY")
headers = {
"Authorization": f"Bearer {API_KEY}",
"Accept": "text/event-stream",
"Content-Type": "application/json",
}
payload = {
"model": MODEL,
"stream": True,
"input": [
{"role": "user", "content": [
{"type": "input_text", "text": "اكتب خطاباً قصيراً من 4 جمل."}
]}
]
}
with requests.post(f"{BASE_URL}/responses", json=payload, headers=headers, stream=True) as r:
r.raise_for_status()
client = sseclient.SSEClient(r)
for event in client.events():
if event.event == "message":
print(event.data)
```
8) أفضل ممارسات الإنتاج
- الموثوقية:
- عيّن مهلة timeout مناسبة (مثلاً 30–180 ثانية حسب الوسائط).
- أعد المحاولة مع backoff أُسيّ على أخطاء 429/5xx، وحدّد أقصى عدد محاولات.
- استخدم مفاتيح idempotency في الطلبات الحرجة لتجنب التكرار.
- التحكم في المعدّل:
- احترم حدود المعدّل؛ نفّذ معدل صفري/قوائم انتظار/دفعات عند الحاجة.
- تثبيت الإصدارات:
- ثبّت model بنسخة محددة إذا كان النظام يدعم الوسوم/الإصدارات؛ راقب التغييرات.
- الأمان:
- لا تحفظ QWEN_API_KEY في الشفرة؛ استخدم أسرار بيئة/خزائن.
- صفّ المعلومات الحساسة قبل التسجيل؛ راقب الضوابط لمنع تسريب البيانات.
- التكلفة والأداء:
- قلّص وسائط الإدخال (ضغط الصور/مقاطع أقصر)، واضبط max_tokens/temperature.
- استخدم التخزين المؤقت للنتائج القابلة لإعادة الاستخدام.
- الصلاحية:
- تحقّق من نوع الملف، الصيغة، الحجم، الطول قبل الإرسال.
- بالنسبة للفيديو، اجعل المقاطع قصيرة وبدقة مناسبة لتقليل زمن المعالجة.
- المراقبة:
- سجّل المعرّفات، زمن الاستجابة، رموز الحالة؛ ضع قياسات لمعدلات النجاح/الفشل.
- الخصوصية:
- حدّد سياسات الاحتفاظ؛ امسح الوسائط بعد اكتمال المعالجة إذا لم تعد مطلوبة.
9) فحوصات توفر CometAPI
- استخدم نقاط صحية/توفّر إن وُجدت؛ إن لم تتوفر، استخدم طلباً خفيفاً للتحقق من الوصول.
- Python: فحص الصحة ونماذج متاحة مع خطة بديلة:
```python
import os, time, requests
COMET_URL = os.getenv("COMET_URL", "https://cometapi.qwen.ai")
API_KEY = os.getenv("QWEN_API_KEY")
def healthy(timeout=5):
try:
r = requests.get(f"{COMET_URL}/health", headers={"Authorization": f"Bearer {API_KEY}"}, timeout=timeout)
return r.ok
except requests.RequestException:
return False
def model_available(model="Qwen3.8-Omni-Flash", timeout=5):
try:
r = requests.get(f"{COMET_URL}/models", headers={"Authorization": f"Bearer {API_KEY}"}, timeout=timeout)
r.raise_for_status()
models = r.json().get("data", [])
return any(m.get("id") == model for m in models)
except requests.RequestException:
return False
def wait_until_ready(max_wait=60, interval=5):
start = time.time()
while time.time() - start < max_wait:
if healthy() and model_available():
return True
time.sleep(interval)
return False
if not wait_until_ready():
# خطة بديلة: التحويل إلى BASE_URL الرئيسي
BASE_URL = os.getenv("BASE_URL", "https://api.qwen.ai/v1")
print("CometAPI غير متاح. سيتم استخدام BASE_URL:", BASE_URL)
else:
print("CometAPI متاح وجاهز.")
```
- cURL: فحص بسيط
```bash
curl -s -o /dev/null -w "%{http_code}\n" \
-H "Authorization: Bearer $QWEN_API_KEY" \
"$COMET_URL/health"
```
- استراتيجيات التبديل:
- ضع طبقة توجيه: جرّب COMET_URL أولاً؛ عند الفشل أو رموز 5xx/429 المرتفعة، تحوّل تلقائياً إلى BASE_URL.
- استخدم cache للحالة الصحية لعدة ثوان لتجنب ضغط نقاط التحقق.
- فعّل دوائر القاطع (circuit breaker): افتح الدائرة بعد أخطاء متتالية، وجرّب نصف مفتوح بعد فترة تهدئة.
10) معالجة الأخطاء والاستجابات
- تحقق من الحقول: output.text، output.audio.data، warnings، usage إن وجدت.
- التزم برموز الحالة:
- 400: تحقّق من الحقول/الصيغ.
- 401/403: اعادة مصادقة.
- 404: تأكد من الاسم MODEL أو المسار.
- 408/429: طبق إعادة المحاولة/backoff.
- 5xx: سجّل وافتح تذكرة/أعد المحاولة بخطّة بديلة.
- اجعل رسائل الخطأ قابلة للتشخيص وقم بتضمين معرفات الطلب عند توفرها.
11) ملاحظات حول الوسائط
- الصور: استخدم JPEG/PNG؛ احفظ الدقة ضمن حدود عملية؛ لا تتجاوز أحجاماً كبيرة بلا حاجة.
- الصوت: فضّل WAV/FLAC/MP3؛ معدلات 16–24 kHz تكفي لمعظم الحالات؛ تأكد من أحادية/ستريو بحسب الحاجة.
- الفيديو: حدّد الطول والدقة؛ استخدم H.264/MP4 الشائع.
- لا تغيّر أسماء الحقول/المفاتيح؛ أرسل الوسائط base64 أو عبر روابط قابلة للوصول حسب ما تدعمه الجهة.
12) مثال متكامل (نص + صورة + إخراج صوت) في Python
```python
import os, requests, base64
BASE_URL = os.getenv("BASE_URL", "https://api.qwen.ai/v1")
MODEL = "Qwen3.8-Omni-Flash"
API_KEY = os.getenv("QWEN_API_KEY")
with open("photo.jpg", "rb") as f:
img_b64 = base64.b64encode(f.read()).decode("utf-8")
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": MODEL,
"modalities": ["text", "audio"],
"audio": {"voice": "female_2", "format": "wav"},
"input": [
{"role": "user", "content": [
{"type": "input_text", "text": "صف الصورة ثم اقرأ الوصف بصوت واضح."},
{"type": "input_image", "image": {"format": "jpg", "data": img_b64}}
]}
]
}
r = requests.post(f"{BASE_URL}/responses", json=payload, headers=headers, timeout=180)
r.raise_for_status()
res = r.json()
desc = res.get("output", {}).get("text", "")
audio_b64 = res.get("output", {}).get("audio", {}).get("data")
print("الوصف:", desc)
if audio_b64:
with open("desc.wav", "wb") as f:
f.write(base64.b64decode(audio_b64))
```
تنبيهات ختامية
- استخدم placeholders مثل BASE_URL وCOMET_URL بحسب بيئتك؛ قد تختلف المسارات الفعلية /responses أو /chat/completions حسب المزود.
- اختبر دائماً صيغ الإدخال/الإخراج المُمكّنة لنموذج Qwen3.8-Omni-Flash (النص/الصور/الصوت/الفيديو/البث) قبل النقل للإنتاج.
- حافظ على اتساق الخيارات (temperature، max_tokens، top_p) وتتبّع usage للتكلفة.
