وثائق واجهة برمجة التطبيقات

تنزيل Python 0.3.7 وNode 0.3.7

تستهدف التنزيلات المثبتة الإصدار في هذه الصفحة Python 0.3.7 وNode 0.3.7 وتشمل اكتشاف النماذج التفصيلي. يلزم Python 3.9 أو أحدث؛ ويتطلب Node.js وMCP المحلي إصدار Node 20 أو أحدث. لا تعني الأرشيفات النشر على npm أو PyPI. لا يحتاج مستخدم SDK العادي لـNode إلى تبعيات MCP الاختيارية.

لا يلزم مصدر العميل أو بيانات اعتماد المزود. شارك اللغة وبيئة التشغيل وإصدار SDK وmodel_code + operation + mode والمعاملات المنقحة وحدود الوسائط وصلاحية URL والاستعادة وميزانية العملة والتزامن. REST هو عقد التنفيذ؛ وSDK عميل خفيف اختياري وMCP المحلي مدخل stdio للوكلاء. يستخدم SDK الخاص أصلاً دون /v1. قد يتطلب SDK المزود تعديل الحقول وإعادة المحاولة؛ تغيير المفتاح أو العنوان وحده لا يضمن التوافق متعدد الوسائط. اتفق على أمثلة منقحة للطلبات والاستجابات والنتائج المتوقعة. اختبر أولاً استجابات اصطناعية 200/202 وGET معلقاً وSSE غير مكتمل وإرسالاً مجهولاً وتسليماً مكرراً؛ يتطلب القبول المدفوع إذناً منفصلاً وميزانية صريحة.

python -m pip install "https://routershift.com/downloads/sdk/routershift-0.3.7-py3-none-any.whl"

سرد النماذج المرئية لمفتاح API

نفّذ أولًا هذا الطلب للقراءة فقط، وانسخ رمز نموذج دقيقًا إلى الأمثلة أدناه. تعرض القائمة ما يمكن للمفتاح رؤيته؛ ولا تثبت تفعيل كل عملية أو وضع لذلك النموذج.

استخدم مفتاح التنفيذ نفسه مع GET /v1/models?details=1: لا ينشئ مهمة ولا يحجز أموالاً ولا يستدعي المزود؛ وتظل المصادقة والسجلات وحدود المعدل سارية. افحص مسارات وأنماط details.operations وconstraints.status وimport_contract.status/reason. احفظ الأبعاد والشروط والعملة والدقة والمحددات ووقت الرصد وsemantic_sha256. السعر المرجعي ليس عقداً قابلاً للتنفيذ. غياب القيود أو جهلها لا يعني مدخلات غير محدودة؛ وavailable لا يضمن الأموال. ليست هذه Schema كاملة لكل نموذج أو إسقاطاً شاملاً للعقود غير الرمزية. يبقى models.list() قائمة عادية افتراضياً؛ اطلب التفاصيل صراحة بأساليب SDK المضمنة أو REST. في constraints تصف available المجموعة المراجعة للعملية؛ وتتطلب unsupported إرشادات العملية المحددة.

ميز details.constraints.operations[].scope: تمثل reviewed_subset مجموعة العملية المراجعة؛ وتنطبق finite_admission_opt_in فقط على الطلبات التي تفعل الحد المحدود صراحة، لا على كل دردشة عادية. ليست parameters مخطط Schema كاملاً للمدخلات. إن وجدت details.admission، افحص status وprofile و/details/admission/required_headers وحدود المدخلات والمخرجات المعلنة؛ وتبقى النماذج المجهولة unavailable. لا يمنح الاكتشاف أموالاً أو سقف تسعير عاماً.

يتضمن Node 0.3.7 الأسلوب listDetails() وخيار details=true في models.list؛ ويتضمن Python 0.3.7 الأسلوبين models.list(details=True) وlist_details(). أساليب الاكتشاف التفصيلي هذه موجودة في حزم هذا الإصدار. يبقى models.list() قائمة عادية افتراضياً؛ ولا تحصل التثبيتات القديمة على الأساليب الجديدة تلقائياً.

curl --fail-with-body --connect-timeout 10 --max-time 30 "https://api.routershift.com/v1/models?details=1" \
  -H "Authorization: Bearer $ROUTERSHIFT_API_KEY"

المحادثات النصية

يمكن لـ Python وNode وMCP استدعاء النماذج النصية. يستطيع الوكيل الاحتفاظ بنموذجه الأساسي واستدعاء RouterShift عند الحاجة. تبقى الصلاحيات والرسوم ضمن واجهة API نفسها.

import os
from routershift import RequestOptions, RouterShift

client = RouterShift(api_key=os.environ["ROUTERSHIFT_API_KEY"])
response = client.chat.completions.create(
    model="YOUR_TEXT_MODEL_CODE",
    messages=[{"role": "user", "content": "Summarize this project in one sentence."}],
    request_options=RequestOptions(max_retries=0),
)
print(response.choices[0].message.content)

طلبات Omni عبر HTTP

يرسل المثال صوت WAV ويطلب نصًا وصوتًا عبر تدفق HTTP. اختر مسارًا متوافقًا مع OpenAI تم التحقق منه، مع وضع stream وصوت يدعمهما النموذج. تتطلب النماذج التي تدعم SSE فقط الخيار stream:true؛ وتقبل routershift_chat هذا الخيار أيضًا. يحتفظ SDK بكتل المحتوى وaudio وmodalities واستدعاءات الأدوات والاستجابات الصوتية. لا يوفر HTTP Omni اتصالات Realtime WebSocket أو تحويلًا عشوائيًا بين بروتوكولات المزوّدين.

import base64
import os
from pathlib import Path
from routershift import RequestOptions, RouterShift

client = RouterShift(api_key=os.environ["ROUTERSHIFT_API_KEY"])
audio_data = base64.b64encode(Path("/absolute/path/to/sample.wav").read_bytes()).decode()
response = client.chat.completions.create(
    model="YOUR_OMNI_MODEL_CODE",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "Describe the sound."},
        {"type": "input_audio", "input_audio": {"data": audio_data, "format": "wav"}},
    ]}],
    stream=True,
    modalities=["text", "audio"],
    audio={"voice": "YOUR_MODEL_VOICE", "format": "wav"},
    request_options=RequestOptions(max_retries=0),
)
for chunk in response:
    if chunk.choices:
        delta = chunk.choices[0].delta or {}
        print(delta.get("content", ""), end="")
        if delta.get("audio"):
            print(delta["audio"].get("transcript", ""), end="")

توليد الكلام

تستدعي audio.speech المسار /v1/audio/speech. يعيد Python بايتات الصوت؛ ويعيد Node بايتات data وقيمة contentType الفعلية. اختر صوتًا وتنسيقًا يدعمهما النموذج. لا يُحفظ الصوت تلقائيًا في ملف محلي.

import os
from routershift import RouterShift

client = RouterShift(api_key=os.environ["ROUTERSHIFT_API_KEY"])
speech = client.audio.speech(
    model="YOUR_SPEECH_MODEL_CODE",
    input="Welcome to RouterShift.",
    voice="YOUR_MODEL_VOICE",
    response_format="wav",
)
print(len(speech))

تفريغ الصوت

ترسل audio.transcribe الملف الصوتي المحدد صراحة بصيغة multipart إلى /v1/audio/transcriptions. احتفظ بامتداد الملف الحقيقي. يطلب المثال JSON ويقرأ text؛ وتعتمد اللغات والتنسيقات المدعومة على المسار.

import os
from pathlib import Path
from routershift import RouterShift

client = RouterShift(api_key=os.environ["ROUTERSHIFT_API_KEY"])
transcript = client.audio.transcribe(
    model="YOUR_TRANSCRIPTION_MODEL_CODE",
    file=Path("/absolute/path/to/sample.wav").read_bytes(),
    filename="sample.wav",
    response_format="json",
)
print(transcript.text)

تفريغ صوت من عنوان HTTPS

استخدم audio.transcribe_url في Python أو audio.transcribeURL في Node.js، أو أرسل JSON يتضمن file_url إلى /v1/transcriptions. تتحقق حزمة SDK من عنوان HTTPS ولا تنزّل التسجيل محليًا. تستخدم علامتا Go وJava عميلَي HTTP القياسيين للغتين؛ ولا تدّعي RouterShift توفير حزم SDK خاصة بها لهما.

import os
from routershift import RouterShift

client = RouterShift(api_key=os.environ["ROUTERSHIFT_API_KEY"])
transcript = client.audio.transcribe_url(
    "YOUR_TRANSCRIPTION_MODEL_CODE",
    "https://media.example/recording.wav",
    language="en",
    audio_format="wav",
    response_format="json",
)
print(transcript.text)

إنشاء الصور والاستعلام عن مهامها

استخدم images.generate مع نموذج مفعّل لإنشاء الصور. للنماذج التي تدعم الصور غير المتزامنة، أضف async_=True في Python أو async: true في Node.js، ثم استعلم عن id المُعاد باستخدام images.retrieve. تتضمن الاستجابة المكتملة data وروابط الصور؛ وتتضمن الاستجابة المعلقة id وstatus.

import os
from routershift import ImageTaskResponse, RouterShift

client = RouterShift(api_key=os.environ["ROUTERSHIFT_API_KEY"])
image = client.images.generate(
    model="YOUR_IMAGE_MODEL_CODE",
    prompt="A quiet garden in watercolor",
)
print(image)
if isinstance(image, ImageTaskResponse):
    print(client.images.retrieve(image.id))

إرسال فيديو والاستعلام عن حالته

يرسل videos.create مهمة فيديو واحدة ويعيد task_id. احفظه قبل الاستعلام عبر videos.retrieve؛ قد لا تحتوي المهمة المعلقة على video_url بعد. يوفر كلا SDK أيضًا videos.poll للانتظار بمدة محدودة. مسار API هو /v1/video/generations، وكلمة video بصيغة المفرد.

تدعم مسارات Seedance وWan 3.0 الأصلية المتحقَّق منها الحقل generate_audio: حذفه يحافظ على إعداد المورد، وfalse يطلب فيديو بلا مسار صوتي، وtrue يطلب الصوت. يحوّله Wan إلى parameters.audio ويُفعّل الصوت افتراضياً حالياً. تبقى تعرفة فيديو Wan نفسها مع الصوت أو بدونه، دون رسم صوتي إضافي. قد لا تدعم المسارات الأخرى الحقل؛ ولا تُحذف القيم الصريحة بصمت.

import os
from routershift import RouterShift

client = RouterShift(api_key=os.environ["ROUTERSHIFT_API_KEY"])
task = client.videos.create(
    model="YOUR_VIDEO_MODEL_CODE",
    prompt="A slow camera movement through a garden",
)
print(task.task_id)
result = client.videos.retrieve(task.task_id)
print(result.status, result.video_url)

إضافة أدوات النماذج إلى الوكيل

أضف أدوات إلى الوكيل عبر MCP، أو استخدم Python/Node SDK في تطبيقك؛ فهما طريقتان متوازيتان للوصول. اتبع خطوات stdio المحلية الأربع ولا تحفظ بيانات الاعتماد في إعدادات مشتركة أو في نظام التحكم بالإصدارات.

1. 1. إنشاء مجلد مخصص وتثبيت MCP

   استخدم Node 20 أو أحدث. يضيف هذا التثبيت المخصص لـ MCP اعتماديتي النظير الخاصتين بالبروتوكول؛ ولا يحتاجهما تثبيت Node SDK العادي.

   shell

   نسخ

   mkdir routershift-mcp
   cd routershift-mcp
   npm init -y
   npm install "https://routershift.com/downloads/sdk/routershift-sdk-0.3.7.tgz" @modelcontextprotocol/server@2.0.0 zod@4.6.4

2. 2. استخراج مسار دخول الخادم المطلق

   شغّل الأمر داخل المجلد الجديد. يطبع مسارًا مطلقًا بتنسيق مهرب لـ JSON يمكنك لصقه في مصفوفة args في الإعداد.

   Node.js

   نسخ

   node -p "JSON.stringify(require('node:path').resolve('node_modules/@routershift/sdk/dist/mcp/cli.js'))"

3. 3. إعداد عميل stdio المحلي

   استبدل مسار المثال، واضبط مفتاح API في بيئتك المحلية فقط، واحتفظ بأصل API الموثوق من دون /v1 أو بيانات اعتماد أو استعلام أو جزء. تستخدم علامة Codex صيغة stdio وenv_vars الموثقة.

   mcpServers JSONCodex TOML

   نسخ

   {
     "mcpServers": {
       "routershift": {
         "command": "node",
         "args": [
           "/absolute/path/to/your/project/node_modules/@routershift/sdk/dist/mcp/cli.js"
         ],
         "env": {
           "ROUTERSHIFT_API_KEY": "sk-REPLACE_LOCALLY",
           "ROUTERSHIFT_BASE_URL": "https://api.routershift.com"
         }
       }
     }
   }

4. 4. إعادة تشغيل الموصل والتحقق من عشر أدوات

   أعد تشغيل عميل MCP أو حمّله من جديد، وتأكد من ظهور الأدوات العشر، ثم استدعِ routershift_list_models للقراءة فقط أولًا. لا تستدعِ أداة نموذج مدفوعة إلا عندما تنوي إرسال تلك العملية.

تتوفر عشر أدوات: routershift_list_models, routershift_estimate_chat, routershift_chat, routershift_generate_image, routershift_create_video, routershift_get_task, routershift_get_request, routershift_speech, routershift_transcribe, routershift_transcribe_url. اختر أولًا نموذجًا يدعم العملية المطلوبة. استعلم عن مهام الصور والفيديو باستخدام routershift_get_task مع kind بقيمة image أو video وtask_id. استعلم عن إيصال الطلب باستخدام routershift_get_request وrequest_id للقراءة فقط؛ فهذا لا يرسل عملية مدفوعة ولا يفعّلها. في 0.3.7 يقرأ details:true تفاصيل النماذج والعقود. يقرأ routershift_estimate_chat حد القبول الأعلى المحدود فقط: بلا استدعاء للمورد أو حجز أموال أو تنفيذ تلقائي؛ funds_verified=false. عرض السعر ليس الفاتورة النهائية ولا إذناً بالتنفيذ.

تقبل routershift_chat مراجع HTTPS للصور والفيديو؛ وتقرأ audio_file مسار WAV/MP3 مطلقًا تختاره صراحة، بحد أقصى 16 MiB. تقرأ routershift_transcribe ملفًا صوتيًا محليًا محددًا عبر file_path؛ بينما تمرر routershift_transcribe_url قيمة file_url عبر HTTPS دون تنزيلها. تُعاد مخرجات الكلام وصوت Omni مضمّنة. تقبل routershift_generate_image قيمة response_format من نوع url أو b64_json؛ وعندما يكون خرج b64_json محدود الحجم وصالحًا بصيغة PNG أو JPEG أو WebP أو GIF، تعيد محتوى image أصليًا في MCP من دون كتابة ملف أو تنزيله أو إعادة استضافته، ومن دون نسخ Base64 إلى JSON نصي. تُحذف صراحة بيانات الصور الأكبر من الحد أو ذات الصيغة المجهولة؛ لا تعِد إرسال طلب مدفوع لاسترجاع خرج محذوف. لا يفحص المحوّل المجلدات ولا يحفظ النتائج تلقائيًا.

تعرض علامة JSON بنية mcpServers الشائعة؛ وتعرض علامة TOML صيغة Codex الموثقة. تختلف مواقع الإعداد وأذونات العمليات الفرعية حسب العميل. يحتاج عملاء MCP البعيد فقط إلى وسيلة نقل مدعومة بصورة منفصلة؛ ولا تدّعي هذه الأمثلة أنها اختُبرت في جميع واجهات الوكلاء.

يتيح محوّل MCP المحلي استدعاء واجهات RouterShift للنصوص والوسائط المتعددة والصوت والمهام. توفر بوابة /v1/mcp الحالية الوصول إلى الأدوات الخارجية المهيأة. ولا تحل إعدادات HTTP/SSE الخاصة بها محل إعدادات أدوات النماذج المحلية الموضحة هنا.