المصادقة

Authorization: Bearer YOUR_API_KEY

x-api-key: YOUR_API_KEY

الترويسات المقبولة

تُقرأ الترويستان على كل نقطة نهاية /v1، أياً كانت الصيغة التي تتحدثها نقطة النهاية. أرسل واحدة منهما.

مع OpenAI SDK، اضبط المفتاح وعنوان base URL؛ وترسل الحزمة Authorization: Bearer.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1"
)

response = client.chat.completions.create(
    model="shannon-3",
    messages=[
        {"role": "user", "content": "Hello, Shannon!"}
    ]
)

print(response.choices[0].message.content)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.shannon-ai.com/v1'
});

const response = await client.chat.completions.create({
  model: 'shannon-3',
  messages: [
    { role: 'user', content: 'Hello, Shannon!' }
  ]
});

console.log(response.choices[0].message.content);

curl -X POST "https://api.shannon-ai.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-3",
    "messages": [
      {"role": "user", "content": "Hello, Shannon!"}
    ]
  }'

مع Anthropic SDK، اضبط المفتاح وعنوان base URL من دون /v1؛ وترسل الحزمة x-api-key.

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com"
)

message = client.messages.create(
    model="shannon-3",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Shannon!"}
    ]
)

print("".join(block.text for block in message.content if block.type == "text"))

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.shannon-ai.com'
});

const message = await client.messages.create({
  model: 'shannon-3',
  max_tokens: 1024,
  messages: [
    { role: 'user', content: 'Hello, Shannon!' }
  ]
});

console.log(message.content.filter((block) => block.type === 'text').map((block) => block.text).join(''));

curl -X POST "https://api.shannon-ai.com/v1/messages" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-3",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, Shannon!"}
    ]
  }'

نقاط النهاية التي تحتاج مفتاحاً

مفتاحك

• المفتاح هو sk- متبوعاً بـ 43 محرفاً من A–Z وa–z و0–9 و- و_: أي 46 محرفاً في المجموع.
• لكل حساب مفتاح واحد بالضبط. يُنشأ عند أول مرة تفتح فيها المفاتيح والاستخدام.
• يمنح المفتاح وصولاً كاملاً إلى API لحسابك: كل نقطة نهاية وكل نموذج والرصيد بأكمله.
• ليس للمفتاح تاريخ انتهاء. يعمل إلى أن تدوّره أو تبطله.

التدوير والإبطال

تدوّر المفتاح وتبطله في صفحة المفاتيح والاستخدام. المفاتيح والاستخدام

• يسري كلاهما فوراً: الطلب التالي بالمفتاح القديم يُجاب بـ 401. اعتبر 60 ثانية الحد الأقصى قبل أن يُرفض المفتاح القديم في كل مكان.
• كل عميل في الحساب يستخدم المفتاح نفسه، لذا يصل التدوير إلى جميعهم. ضع المفتاح الجديد في عملائك مباشرة بعد التدوير.
• الرصيد والاستخدام والحماية من الإغراق تتبع الحساب لا المفتاح. المفتاح الجديد يواصل بالرصيد نفسه وبعدد الطلبات نفسه للدقيقة الحالية.

الأخطاء

كل فشل في المصادقة له الحالة 401 والنوع authentication_error. وتفرّق الرسالة بين الحالات.

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "invalid_api_key",
    "param": null
  }
}

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

• في كل مسار عدا /v1/messages يحتوي الكائن error أيضاً على code: "invalid_api_key"، حتى عند غياب المفتاح، وعلى param: null.
• يُفحص المفتاح قبل قراءة النص. الطلب بلا مفتاح صالح يحصل على 401 حتى لو كان نصه غير صالح أو كبيراً جداً.
• قيمة Authorization: Bearer التي لا تبدأ بـ sk- لا تُعامل كمفتاح API. تحصل على 401 مع رسالة تفيد بأن الـ token غير صالح أو منتهي الصلاحية.

المتصفحات وCORS

• تجيب API على طلبات المتصفح عبر الأصول المختلفة (cross-origin) فقط لقائمة ثابتة من الأصول. لا تستطيع JavaScript في صفحة من أصل آخر قراءة ردود /v1.
• استدعِ API من خادمك ودع صفحتك تتحدث إلى خادمك. وهذا يُبقي المفتاح خارج مصدر الصفحة أيضاً.
• لا يتأثر بذلك الكود من جهة الخادم وأدوات سطر الأوامر: هذه القاعدة تطبقها المتصفحات فقط.
• تسجيل الدخول على shannon-ai.com لا يصادق طلبات /v1. لا تُقرأ ملفات تعريف الارتباط هناك؛ والمفتاح هو بيانة الاعتماد الوحيدة.
• لأصل (origin) مسموح به، يجوز للمتصفح إرسال content-type وauthorization وx-api-key وanthropic-version وanthropic-beta وopenai-beta وx-request-id، ويجوز له قراءة ترويسة الرد x-request-id.

حماية المفتاح

• أبقِ المفتاح على خادم. لا تضعه في صفحات الويب أو تطبيقات الجوال أو المستودعات العامة: من يملكه يستطيع إنفاق رصيدك بالكامل.
• حمّل المفتاح من متغير بيئة أو من مخزن أسرار بدلاً من كتابته في الشيفرة.
• إذا احتمل أن المفتاح قد تسرّب، فدوّره في المفاتيح والاستخدام. يتوقف المفتاح القديم عن العمل فوراً.
• بعد أي تسريب، اقرأ قائمة الطلبات في المفاتيح والاستخدام. تعرض كل طلب أجراه المفتاح خلال آخر 30 يوماً.