مرجع Uncensored API، موضح حقلاً بحقل

الاتفاقيات والنقل

عنوان URL الأساسي هو https://api.uncensoredapis.com/v1. جميع الأجسام بصيغة JSON وUTF-8. يحمل كل طلب Authorization: Bearer <key>؛ والمفتاح المفقود أو الخاطئ يعيد 401. يوجد طريقتان فقط، وأي مسار آخر يعيد 404.

الطريقة	المسار	الغرض
POST	/v1/chat/completions	توليد رسالة المساعد، يمكن بثها متدفقاً
GET	/v1/models	قائمة معرف النموذج الذي يمكنك طلبه

واجهة برمجة التطبيقات تدعم النصوص فقط. لا توجد مسارات للترميز النصي (embeddings) أو الصور أو الصوت أو الفيديو، ولا يوجد ضبط دقيق (fine-tuning)، وهناك نموذج واحد بالضبط، يُشار إليه باسم uncensored. نظرًا لأن تنسيق السلك متوافق مع اتفاقية إكمال الدردشة، فإن مكتبي Python وNode الرسمية تعملان عند تجاوز base_url. تغطي الوثائق إعداد التشغيل الأولي؛ وهذه الصفحة هي المرافق على مستوى الحقول.

حقول جسم الطلب

تجدد الجدول الحقول التي تفهمها نقطة النهاية. يتم تمرير حقول العينة إلى التوليد دون تغيير، لذا فإن القيم التي تختارها تتصرف كما في أي API على نمط إكمال الدردشة.

الحقل	النوع	ملاحظات
model	string	دائماً "uncensored".
messages	array	كائنات مرتبة مع role (system، user، assistant، tool) و content.
max_tokens	integer	حد الإكمال. الافتراضي 2048، الحد الأقصى 32,000.
temperature	number	العشوائية. الأقل أكثر حتمية.
top_p	number	حد العينة النووية.
stop	string or array	تسلسلات تنتهي التوليد.
stream	boolean	يُفعّل true البث المتدفق عبر أحداث مرسلة من الخادم.
tools	مصفوفة	تعريفات الدوال بتنسيق JSON-schema القياسي.

إليك طلب مُعلّق كامل. يحدد رسالة النظام السلوك، وتحمل رسالة المستخدم المهمة، وينهي stop التوليد عند أول سطر فارغ.

Copycurl https://api.uncensoredapis.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [
      {"role": "system", "content": "You are a terse release-notes writer."},
      {"role": "user", "content": "Summarize: fixed login bug, added dark mode."}
    ],
    "max_tokens": 120,
    "temperature": 0.4,
    "stop": ["\n\n"]
  }'

قواعد الميزانية اثنتان مهمتان. أولاً، يجب أن يتسع الموجّه بالإضافة إلى اكتمال النص إلى 100,000 رمز، لذا يُرفض الطلب الذي يتجاوز مجموع رموز الموجّه وmax_tokens هذا الحد برمز 400. ثانياً، لا يجوز أن يتجاوز جسم الطلب المُسلسل 8 ميجابايت. إذا كنت ترسل سجلات طويلة، قم بقص المحادثات القديمة من جانبك قبل أن تقترب من أي من هذين الحدّين.

كائن الاستجابة

يعيد المكالمة غير المتدفقة كائناً واحداً بصيغة JSON. اقرأه من الأعلى إلى الأسفل كما يلي.

Copy{
  "id": "chatcmpl-example123",
  "object": "chat.completion",
  "created": 1767225600,
  "model": "uncensored",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "v1.4: Login bug fixed. Dark mode added."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 38,
    "completion_tokens": 14,
    "total_tokens": 52
  }
}

• id: معرّف فريد للإكمال. سجّله بجانب معرف طلبك الخاص عند الحاجة إلى ربط الأحداث.
• object: الثابت chat.completion.
• created: طابع زمني يونيكس بالثواني.
• model: يعكس uncensored.
• choices: مصفوفة. تتلقّى مدخلاً واحداً، لذا فإن choices[0] هو الجواب. يشير index إلى موقعه.
• choices[].message: قيمة role هي assistant؛ يحمل content النص، أو يكون null عندما يُرجع النموذج استدعاءات للأدوات.
• choices[].finish_reason: سبب توقف التوليد؛ انظر القسم التالي.
• usage: محاسبة الرموز للفوترة، مغطاة أدناه.

قيم finish_reason

فرّع بناءً على finish_reason قبل الوثوق بالمحتوى. تبدو الإجابة المقطوعة والإجابة الكاملة متطابقتين حتى تقوم بفحصها.

القيمة	المعنى	ما يجب أن يفعله الكود الخاص بك
stop	وصل النموذج إلى نهاية طبيعية أو استوفى أحد تسلسلات التوقف stop الخاصة بك.	استخدم المحتوى كما هو.
length	تم الوصول إلى حدّ max_tokens (أو نافذة السياق) أثناء الإجابة.	ارفع قيمة max_tokens، أو قصّ الموجّه، أو اطلب من النموذج الاستمرار.
tool_calls	يريد النموذج تشغيل دالة واحدة أو أكثر.	نفّذها وأرسل النتائج كرسائل tool.

عندما تكون القيمة tool_calls، تبدو الرسالة كما يلي، مع تسليم الحجج كـ JSON string يجب عليك تحليلها بنفسك:

Copy{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc1",
        "type": "function",
        "function": {"name": "get_order", "arguments": "{\"order_id\": 8841}"}
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

قم دائمًا بتغليف json.loads أو JSON.parse على arguments في معالجة الأخطاء، لأن JSON المُولّد قد يكون أحيانًا غير صالح.

كتلة الاستخدام والتكلفة

يُبلغ usage عن prompt_tokens، وcompletion_tokens، وtotal_tokens. هذه هي الأرقام التي يُخصم رصيدك منها: المدخلات بسعر 0.25 دولار لكل مليون رمز، والمخرجات بسعر 1.00 دولار لكل مليون. يُخصم الرصيد المسبق لكل طلب، بدون اشتراك.

مثال عملي تحت افتراضات محددة: لنفترض أن طلبًا يستخدم 2,000 رمز موجّه و500 رمز إكمال. تكلفة المدخلات هي 2,000 / 1,000,000 × 0.25 دولار = 0.0005 دولار. تكلفة المخرجات هي 500 / 1,000,000 × 1.00 دولار = 0.0005 دولار. يبلغ إجمالي الطلب 0.0010 دولار. هذه أعداد الرموز هي افتراضات للحسابات، وليست قياسًا لأي عبء عمل حقيقي. تحتوي صفحة التسعير على الأسعار في مكان واحد.

نظرًا لأن تكلفة الرموز المخرجة تساوي أربعة أضعاف تكلفة الرموز المدخلة، فإن ضبط max_tokens بدقة هو أكثر وسائل التحكم في التكلفة مباشرة.

تنسيق كتل البث المتدفق

اضبط "stream": true، وستصبح الاستجابة بصيغة text/event-stream. كل حدث هو سطر يبدأ بـ data: متبوعًا بـ JSON، مفصول بسطر فارغ. يتغير نوع الكائن إلى chat.completion.chunk، ويُستبدل message بـ delta.

Copydata: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"v1.4: "},"finish_reason":null}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Login bug fixed."},"finish_reason":null}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-example123","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":38,"completion_tokens":14,"total_tokens":52}}

data: [DONE]

1. تضبط الكتلة الأولى عادةً delta.role إلى assistant بمحتوى فارغ.
2. تحمل أجزاء المحتوى جزءًا في delta.content. اجمعها بترتيب الوصول.
3. تحتوي كتلة الإغلاق على delta فارغ وfinish_reason غير فارغ.
4. يحمل جزء نهائي بمصفوفة choices فارغة بيانات usage. لا تطلبها؛ يتم إضافتها تلقائيًا.
5. النص الحرفي data: [DONE] ينهي البث.

احمِ نفسك من هذه المصفوفة الفارغة choices: يؤدي الوصول إلى choices[0] في جزء الاستخدام إلى رفع خطأ في الحلقات البسيطة. يعالج مثال المكتبة أدناه ذلك.

Copyimport os
from openai import OpenAI

client = OpenAI(base_url="https://api.uncensoredapis.com/v1", api_key=os.environ["API_KEY"])

reason, usage = None, None
for chunk in client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Name three uses of a rubber duck in debugging."}],
    stream=True,
):
    if chunk.choices:
        piece = chunk.choices[0].delta.content
        if piece:
            print(piece, end="", flush=True)
        if chunk.choices[0].finish_reason:
            reason = chunk.choices[0].finish_reason
    if getattr(chunk, "usage", None):
        usage = chunk.usage

print("\nfinish:", reason, "| tokens:", usage.total_tokens if usage else "n/a")

بالنسبة إلى استدعاءات الأدوات المتدفقة، يصل delta.tool_calls في أجزاء؛ اجمع سلسلة arguments لكل فهرس استدعاء وقم بالتحليل مرة واحدة عندما يكون finish_reason مساويًا لـ tool_calls.

نقطة النهاية الخاصة بالنماذج

يتطلب GET /v1/models رأس Bearer فقط ويعيد كائن قائمة. نظرًا لوجود نموذج واحد، يحتوي data على إدخال واحد، وهو uncensored. لذلك، سيعرض العملاء الذين يملأون قائمة منسدلة للنماذج من هذا المسار خيارًا واحدًا فقط.

Copycurl https://api.uncensoredapis.com/v1/models -H "Authorization: Bearer $API_KEY"

{
  "object": "list",
  "data": [
    {"id": "uncensored", "object": "model"}
  ]
}

إنها أيضًا أرخص طريقة للتحقق من مفتاح: يعني 200 أن المفتاح صالح، ويعني 401 أنه خاطئ أو تم إعادة توليده. لا يولد استدعاء هذا المسار رموزًا. لمعالجة الأخطاء ومعدلات الحد، انظر إلى دليل الأخطاء ومعدلات الحد.

قائمة مرجعية لمطوري العملاء

إذا كنت تكتب مكتبة عميل أو تغلف نقطة النهاية في بوابة، تحقق من كل سلوك من هذه السلوكيات مقابل المواصفات أعلاه قبل النشر.

1. نظافة الرؤوس. أرسل المفتاح فقط في رأس Authorization، وليس في سلسلة الاستعلام، ولا تسجل قيمة الرأس أبداً.
2. التحليل الدفاعي. تعامل مع الحقول الإضافية المجهولة في الاستجابات على أنها قابلة للتجاهيل. ثبّت المحلل الخاص بك على الحقول الموثقة هنا بدلاً من ترتيب مفاتيح JSON الدقيق.
3. تحقق من finish_reason في كل رد. اعرض مؤشرًا مرئيًا عندما تكون القيمة مساوية لـ length، لأن المستخدمين يقرأون النص المقطوع على أنه الإجابة الكاملة.
4. الميزانية قبل الإرسال. قدّر رموز الموجّه، وأضف max_tokens الخاص بك، وقارن المجموع بـ 100,000. الرفض محلياً أسرع من انتظار خطأ 400.
5. عالج نهاية التدفق. توقع جزءًا بقائمة choices فارغة وكائن usage، ثم [DONE]. أغلق الاتصال بعد إشارة النهاية.
6. سجّل الاستخدام. احفظ total_tokens لكل طلب حتى تتمكن من مطابقة قياسك الخاص مع الرصيد المسبق لاحقًا.
7. احترم الحد الأعلى. يسمح الحساب بـ 300 طلب في الدقيقة لكل مفتاح، لذا تحتاج البوابة التي توزع على العديد من المستخدمين إلى طابور خاص بها.

لا تعتمد أي من هذه الخطوات على مكتبة SDK من مورد معين. يكفي عميل HTTP عادي يضبط رأس Bearer ويفك تشفير JSON، ومكتبات SDK المعروضة في هذه الصفحة هي مجرد ميزات مريحة وليست متطلبات. اجمع قائمة التحقق هذه مع جدول الأخطاء في الدليل وستغطي دورة حياة الطلب بأكملها: البناء، الإرسال، التدفق، التحليل، المحاسبة، والاستعادة.