توثیق

Authorization: Bearer YOUR_API_KEY

x-api-key: YOUR_API_KEY

قبول کیے جانے والے ہیڈرز

دونوں ہیڈرز ہر /v1 endpoint پر پڑھے جاتے ہیں، چاہے endpoint کوئی بھی فارمیٹ بولتا ہو۔ ان میں سے ایک بھیجیں۔

OpenAI SDK کے ساتھ کلید اور بیس URL سیٹ کریں؛ SDK 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 کے ساتھ کلید اور /v1 کے بغیر بیس URL سیٹ کریں؛ SDK 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!"}
    ]
  }'

کن endpoints کو کلید چاہیے

آپ کی کلید

• کلید sk- اور اس کے بعد A–Z، a–z، 0–9، - اور _ میں سے 43 حروف پر مشتمل ہوتی ہے: کل 46 حروف۔
• ہر اکاؤنٹ کے پاس بالکل ایک کلید ہوتی ہے۔ یہ پہلی بار Keys & usage کھولنے پر بنتی ہے۔
• کلید آپ کے اکاؤنٹ کے لیے API تک مکمل رسائی دیتی ہے: ہر endpoint، ہر ماڈل اور پورا بیلنس۔
• کلید کی کوئی میعاد ختم ہونے کی تاریخ نہیں ہوتی۔ یہ اس وقت تک کام کرتی ہے جب تک آپ اسے تبدیل یا منسوخ نہ کریں۔

Rotate اور منسوخ کرنا

آپ کلید کو Keys & usage صفحے پر rotate اور منسوخ کرتے ہیں۔ Keys & usage

• دونوں فوراً اثر کرتے ہیں: پرانی کلید کے ساتھ اگلی درخواست کا جواب 401 ہوتا ہے۔ پرانی کلید ہر جگہ مسترد ہونے تک زیادہ سے زیادہ مدت 60 سیکنڈ سمجھیں۔
• اکاؤنٹ کے تمام کلائنٹس ایک ہی کلید استعمال کرتے ہیں، اس لیے rotation سب تک پہنچتی ہے۔ rotate کرنے کے فوراً بعد نئی کلید اپنے کلائنٹس میں ڈالیں۔
• بیلنس، استعمال اور flood protection اکاؤنٹ سے تعلق رکھتے ہیں، کلید سے نہیں۔ نئی کلید اسی بیلنس اور موجودہ منٹ کی اسی درخواستوں کی گنتی کے ساتھ جاری رہتی ہے۔

ایررز

ہر توثیقی ناکامی کا اسٹیٹس 401 اور type 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 ملتا ہے اور پیغام میں بتایا جاتا ہے کہ ٹوکن غلط ہے یا ختم ہو چکا ہے۔

براؤزرز اور CORS

• API کراس اوریجن براؤزر درخواستوں کا جواب صرف origins کی ایک مقررہ فہرست کے لیے دیتی ہے۔ کسی دوسرے 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 پڑھ سکتا ہے۔

کلید کو محفوظ رکھنا

• کلید کو سرور پر رکھیں۔ اسے ویب صفحات، موبائل ایپس یا عوامی ریپوزٹریز میں نہ ڈالیں: جس کے پاس بھی یہ ہو وہ آپ کا پورا بیلنس خرچ کر سکتا ہے۔
• کلید کو کوڈ میں لکھنے کے بجائے environment variable یا سیکرٹ سٹور سے لوڈ کریں۔
• اگر کلید لیک ہو سکتی ہے تو اسے Keys & usage پر rotate کریں۔ پرانی کلید فوراً کام کرنا بند کر دیتی ہے۔
• لیک کے بعد Keys & usage پر درخواستوں کی فہرست پڑھیں۔ یہ پچھلے 30 دنوں میں کلید سے کی گئی ہر درخواست دکھاتی ہے۔