مواد پر جائیں
جائزہ

جائزہ

API کا نقشہ: ہر endpoint، درخواست اور ایرر کیسے دکھتے ہیں، کالز کی ادائیگی کیسے ہوتی ہے، اور جب آپ OpenAI یا Anthropic SDK سے آئیں تو کیا جاننا چاہیے۔

Endpoints

ہر endpoint ایک بیس URL کے تحت ہے اور HTTPS پر فراہم کیا جاتا ہے۔

بیس URL 
https://api.shannon-ai.com
اینڈ پوائنٹ فارمیٹ یہ کس لیے ہے
POST /v1/chat/completions OpenAI Chat Completions گفتگو بھیجیں، اگلا جواب لیں۔ سٹریمنگ کے ساتھ یا بغیر۔
POST /v1/messages Anthropic Messages وہی، Anthropic SDKs کی درخواست اور جواب کی شکلوں میں۔
POST /v1/responses OpenAI Responses وہی، Responses کی شکلوں میں۔ endpoint کوئی حالت نہیں رکھتا: ہر درخواست کے ساتھ گفتگو بھیجیں۔
GET /v1/models OpenAI ماڈل فہرست ماڈلز کو کانٹیکسٹ ونڈو، قیمتوں اور صلاحیتوں کے ساتھ فہرست کریں۔ کلید کی ضرورت نہیں۔
POST /v1/tokenize Shannon API ہوسٹڈ اوپن ویٹ ماڈل کے لیے کسی متن یا چیٹ درخواست کے ٹوکنز گنیں۔ مفت۔
POST /v1/messages/count_tokens Anthropic ٹوکن گنتی ہوسٹڈ اوپن ویٹ ماڈل کے لیے Messages درخواست کے ان پٹ ٹوکنز گنیں۔ مفت۔

متن پیدا کرنے والے تینوں endpoints ایک ہی ماڈلز تک پہنچتے ہیں۔ وہ چنیں جس کا فارمیٹ آپ کا کوڈ پہلے سے استعمال کرتا ہے۔

درخواست کی بنیادی باتیں

ہیڈر تفصیل
Authorization: Bearer <key> آپ کی API کلید۔ GET /v1/models کے سوا ہر endpoint پر لازمی، سوائے اس کے کہ آپ x-api-key بھیجیں۔
x-api-key: <key> وہی کلید اس ہیڈر میں جو Anthropic SDKs بھیجتے ہیں۔ ہر endpoint پر پڑھا جاتا ہے۔
Content-Type: application/json ہر POST پر لازمی۔ اس کے بغیر جواب 415 ہے۔
x-request-id: <your id> اختیاری۔ درخواست کے لیے آپ کا اپنا id؛ یہ جواب کے ہیڈر x-request-id میں واپس آتا ہے۔ اس کے بغیر API 12 ہیکسا ڈیسیمل حروف کا ایک id بنا دیتی ہے۔
  • ہر POST کی باڈی ایک JSON آبجیکٹ ہوتی ہے، 32 MiB تک۔
  • جو فیلڈ API نہیں جانتی وہ کوئی ایرر پیدا نہیں کرتا اور کوئی اثر نہیں رکھتا۔ کسی دوسرے پرووائیڈر کے لیے لکھی گئی درخواست اضافی فیلڈ کی وجہ سے ناکام نہیں ہوتی۔
  • معلوم فیلڈ جس کی JSON قسم غلط ہو، یا لازمی فیلڈ غائب ہو، اس کا جواب 422 سے دیا جاتا ہے۔ جو باڈی درست JSON نہ ہو اس کا جواب 400 سے دیا جاتا ہے۔
  • model ماڈلز اور قیمتیں صفحے پر موجود ids میں سے ایک ہے۔ بڑے اور چھوٹے حروف سے فرق نہیں پڑتا۔

جواب JSON ہوتا ہے، یا server-sent events کی سٹریم جب درخواست stream کو true پر سیٹ کرے۔ ہر endpoint اپنے فارمیٹ میں جواب دیتا ہے۔ ہر جواب میں ہیڈر x-request-id ہوتا ہے۔

درخواست کن جانچوں سے گزرتی ہے

ماڈل کے چلنے سے پہلے درخواست ایک مقررہ ترتیب میں جانچی جاتی ہے۔ جو پہلی جانچ ناکام ہو وہی جواب دیتی ہے، اس لیے 401 ابھی باڈی کے بارے میں کچھ نہیں بتاتا۔

جانچ، اس ترتیب میں ناکامی پر اسٹیٹس
API کلید 401
باڈی: سائز، content type، JSON، فیلڈ کی اقسام 413 · 415 · 400 · 422
ماڈل id 400
Flood protection: فی اکاؤنٹ 120 درخواستیں فی منٹ 429
بیلنس: درخواست کا آؤٹ پٹ بجٹ سمانا چاہیے 429

ایرر کی شکل

ایرر ایک JSON آبجیکٹ ہے جس میں error ہوتا ہے جو type اور message رکھتا ہے۔ /v1/messages اسے ویسے لپیٹتا ہے جیسا Anthropic SDKs توقع کرتے ہیں؛ باقی ہر راستہ OpenAI کی شکل استعمال کرتا ہے۔

{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}
  • type اور message پڑھیں۔ code اور param صرف کچھ ایررز پر موجود ہوتے ہیں: انہیں اختیاری سمجھیں۔ param ہمیشہ null ہوتا ہے۔
  • سٹریم شروع ہونے کے بعد اسٹیٹس پہلے ہی 200 ہوتا ہے۔ اس کے بعد کی ناکامی سٹریم کے اندر ایرر فریم کے طور پر آتی ہے۔
  • ہر ایرر جواب میں ہیڈر x-request-id ہوتا ہے۔
اسٹیٹس قسم کب
400 invalid_request_error باڈی درست JSON نہیں ہے، ماڈل id نامعلوم ہے، یا ماڈل آپ کے بھیجے ہوئے ان پٹ کی کوئی قسم نہیں لیتا۔
401 authentication_error کلید غائب ہے یا درست نہیں۔
404 not_found_error راستہ موجود نہیں۔
405 api_error راستہ موجود ہے، میتھڈ غلط ہے۔
413 invalid_request_error باڈی 32 MiB سے بڑی ہے۔
415 invalid_request_error Content-Type کی قدر application/json نہیں ہے۔
422 invalid_request_error کسی فیلڈ کی JSON قسم غلط ہے یا کوئی لازمی فیلڈ غائب ہے۔
429 rate_limit_error بیلنس درخواست کے لیے کافی نہیں، ایک منٹ میں 120 سے زیادہ درخواستیں آئیں، ونڈو کی Shannon Coder کالز ختم ہو چکی ہیں، یا ماڈل مصروف ہے۔ پیغام بتاتا ہے کہ کون سا۔
5xx api_error اسٹیٹس 500، 502، 503 یا 504: درخواست درست تھی اور اس کا جواب نہیں دیا جا سکا۔ اسے دوبارہ بھیجیں۔ 500 میں type server_error ہو سکتی ہے۔

غلطیاں

بلنگ اور بیلنس

  • ہر اکاؤنٹ کا ایک بیلنس ہے، اور چیٹ اور API اسے مشترکہ استعمال کرتے ہیں: پہلے آج کا پلان الاؤنس، پھر خریدا ہوا کریڈٹ۔ API کا اپنا کوئی کوٹہ نہیں۔
  • درخواست اپنا آؤٹ پٹ بجٹ (max_tokens، ڈیفالٹ 4,096) محفوظ کرتی ہے اور پھر جو ٹوکنز واقعی استعمال ہوئے ان کا چارج ماڈل کی قیمت پر لگتا ہے۔
  • ہر جواب اپنے ٹوکنز کی گنتی usage میں رپورٹ کرتا ہے۔ Keys & usage صفحہ بیلنس اور ہر درخواست کی لاگت دکھاتا ہے۔
  • ہر درخواست کو برابر سروس ملتی ہے۔ درخواستوں کی رفتار پر واحد حد flood protection ہے: فی اکاؤنٹ 120 درخواستیں فی منٹ۔ متوازی بھیجی گئی درخواستیں قطار میں انتظار کرتی ہیں۔

حدود اور بیلنس ماڈلز اور قیمتیں Keys & usage

ماڈل پر منحصر فیلڈز

ہر ماڈل ایک ہی درخواست لیتا ہے۔ کچھ فیلڈز صرف چند ماڈلز پر اثر کرتے ہیں؛ جدول بتاتا ہے کہاں۔ endpoint کے صفحات ہر فیلڈ کی فہرست دیتے ہیں۔

فیلڈ تفصیل لاگو کرنے والے
system ماڈل کے لیے ہدایات: Chat Completions پر system پیغام، Messages پر system، Responses پر instructions۔ ہوسٹڈ اوپن ویٹ ماڈلز، shannon-1.6-*، shannon-2-*، shannon-coder-1
temperature سیمپلنگ ٹمپریچر۔ ہوسٹڈ اوپن ویٹ ماڈلز، shannon-1.6-*، shannon-coder-1
top_p نیوکلیئس سیمپلنگ۔ ہوسٹڈ اوپن ویٹ ماڈلز
seed سیمپلنگ کے لیے مقررہ seed۔ ہوسٹڈ اوپن ویٹ ماڈلز
stop زیادہ سے زیادہ 4 stop sequences۔ ہوسٹڈ اوپن ویٹ ماڈلز
reasoning_effort جواب دینے سے پہلے ماڈل کتنی reasoning کرتا ہے۔ Responses پر reasoning.effort، Messages پر thinking۔ ہوسٹڈ اوپن ویٹ ماڈلز
web_search true ماڈل کو اس درخواست کے لیے ویب پر تلاش کرنے دیتا ہے۔ اس API کا فیلڈ، Chat Completions اور Messages پر۔ shannon-coder-1 کے سوا Shannon ماڈلز
max_tokens آؤٹ پٹ بجٹ۔ ہر ماڈل پر یہ آپ کے بیلنس سے محفوظ کی جانے والی مقدار طے کرتا ہے۔ جواب کی لمبائی کی حد کے طور پر: ہوسٹڈ اوپن ویٹ ماڈلز، shannon-1.6-*، shannon-coder-1

Chat Completions

OpenAI SDK سے آنے والوں کے لیے

  • بیس URL کو https://api.shannon-ai.com/v1 پر سیٹ کریں اور کلید کو اپنی Shannon کلید پر۔ پھر Chat Completions اور Responses کالز SDK کے ساتھ جوں کی توں کام کرتی ہیں۔
  • model کو Shannon id ہونا چاہیے۔ کسی دوسرے پرووائیڈر کے ماڈل کا نام، جیسے gpt-4o، 400 اور unknown model سے جواب پاتا ہے۔
  • reasoning اپنے الگ فیلڈ میں آتی ہے: content کے ساتھ reasoning_content، پیغام میں اور سٹریم ڈیلٹاز میں۔
  • سٹریم اپنے آخری chunk میں finish_reason کے ساتھ ہمیشہ usage رکھتی ہے۔
  • سٹریم میں ٹول کال ایک chunk کے طور پر مکمل arguments سٹرنگ کے ساتھ آتی ہے۔
  • جواب میں ایک choice ہوتی ہے۔
  • OpenAI API کے وہ راستے جو اوپر کے جدول میں نہیں، جیسے /v1/embeddings، 404 سے جواب پاتے ہیں۔

Anthropic SDK سے آنے والوں کے لیے

  • بیس URL کو https://api.shannon-ai.com پر سیٹ کریں، /v1 کے بغیر، اور کلید کو اپنی Shannon کلید پر۔ SDK اسے x-api-key کے طور پر بھیجتا ہے۔
  • model کو Shannon id ہونا چاہیے۔
  • اس API پر max_tokens اختیاری ہے۔ اس کا ڈیفالٹ 4,096 ہے۔
  • جواب میں thinking، text اور tool_use قسم کے مواد کے بلاکس ہوتے ہیں۔ پہلا بلاک ہمیشہ متن نہیں ہوتا: بلاکس کو type سے چنیں۔
  • stop_reason کی قدر end_turn یا tool_use ہے۔ Shannon ماڈل کی سٹریم max_tokens پر بھی ختم ہو سکتی ہے۔
  • anthropic-version اور anthropic-beta قبول کیے جاتے ہیں، اس لیے SDK بغیر تبدیلی کے کام کرتا ہے۔ درخواست کو ان کی ضرورت نہیں۔
  • /v1/messages پر ایررز کی شکل Anthropic جیسی ہے: {"type": "error", "error": {…}}۔

جو کوڈنگ ٹولز یہ فارمیٹس بولتے ہیں وہ اسی طرح سیٹ اپ ہوتے ہیں: بیس URL، کلید، اور ماڈل کے طور پر ایک Shannon id۔ CLI کوڈنگ ٹولز