فوری آغاز

پہلی درخواست کریں: اپنی کلید حاصل کریں، ایک پیغام بھیجیں اور جواب پڑھیں۔ API OpenAI اور Anthropic فارمیٹس بولتی ہے، اس لیے جو SDK آپ پہلے سے استعمال کرتے ہیں وہ بیس URL اور کلید بدلنے کے بعد کام کرتا ہے۔

1. اپنی کلید حاصل کریں

ہر اکاؤنٹ کی ایک API کلید ہے۔ سائن ان کریں، Keys & usage کھولیں اور اسے کاپی کریں۔ کلید ہر endpoint اور ہر ماڈل پر کام کرتی ہے۔ Keys & usage

2. اپنے کلائنٹ کو API کی طرف کریں

تمام endpoints ایک بیس URL کے تحت ہیں۔ OpenAI SDK اسے آخر میں /v1 کے ساتھ لیتا ہے؛ Anthropic SDK اس کے بغیر لیتا ہے، کیونکہ وہ /v1/messages خود شامل کرتا ہے۔

کلائنٹ	بیس URL
OpenAI SDKs اور OpenAI سے ہم آہنگ کلائنٹس	`https://api.shannon-ai.com/v1`
Anthropic SDKs	`https://api.shannon-ai.com`

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

اینڈ پوائنٹ	فارمیٹ
`POST /v1/chat/completions`	OpenAI Chat Completions
`POST /v1/messages`	Anthropic Messages
`POST /v1/responses`	OpenAI Responses

3. پہلی درخواست بھیجیں

Chat Completions endpoint پر shannon-3 کو ایک user پیغام بھیجیں۔ YOUR_API_KEY کی جگہ اپنی کلید لکھیں۔

POST https://api.shannon-ai.com/v1/chat/completions

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!"}
    ],
    max_tokens=1024
)

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!' }
  ],
  max_tokens: 1024
});

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

package main

import (
    "context"
    "fmt"
    openai "github.com/sashabaranov/go-openai"
)

func main() {
    config := openai.DefaultConfig("YOUR_API_KEY")
    config.BaseURL = "https://api.shannon-ai.com/v1"
    client := openai.NewClientWithConfig(config)

    resp, err := client.CreateChatCompletion(
        context.Background(),
        openai.ChatCompletionRequest{
            Model: "shannon-3",
            Messages: []openai.ChatCompletionMessage{
                {Role: "user", Content: "Hello, Shannon!"},
            },
            MaxTokens: 1024,
        },
    )
    if err != nil {
        panic(err)
    }
    fmt.Println(resp.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!"}
    ],
    "max_tokens": 1024
  }'

فیلڈ	قسم	ڈیفالٹ	تفصیل
`model`	`string`		جواب دینے والے ماڈل کا id۔ ids ماڈلز اور قیمتیں پر درج ہیں۔
`messages`	`array`		اب تک کی گفتگو: `role` اور `content` والے آبجیکٹس۔ آخری `user` پیغام پرامپٹ ہے۔ لازمی۔
`max_tokens`	`integer`	`4096`	درخواست کا آؤٹ پٹ بجٹ، 1 سے 65,536 تک۔ درخواست یہ مقدار آپ کے بیلنس سے محفوظ کرتی ہے اور جو واقعی استعمال ہوا اس کا چارج لگتا ہے۔
`stream`	`boolean`	`false`	`true` جواب کو لکھے جانے کے ساتھ ٹکڑا ٹکڑا بھیجتا ہے۔

درخواست کی باڈی JSON ہے اور اسے ہیڈر Content-Type: application/json چاہیے۔ فیلڈز کی مکمل فہرست endpoint کے صفحے پر ہے۔ Chat Completions

جواب

stream کے بغیر کال جواب مکمل ہونے پر ایک JSON آبجیکٹ لوٹاتی ہے۔ نیچے کے متن اور اعداد مثالیں ہیں۔

200 JSON

{
  "id": "chatcmpl-9b2f6c1e4a7d4f0f8a3c5d2e1b6a7c90",
  "object": "chat.completion",
  "created": 1791590400,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! What would you like to work on?",
        "reasoning_content": "A greeting. A short, friendly reply fits."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1386,
    "completion_tokens": 74,
    "total_tokens": 1460
  }
}

فیلڈ	قسم	تفصیل
`id`	`string`	`chatcmpl-` کے بعد 32 ہیکسا ڈیسیمل حروف۔
`object`	`string`	ہمیشہ `chat.completion`۔
`created`	`integer`	جواب کا وقت Unix سیکنڈز میں۔
`model`	`string`	جواب دینے والے ماڈل کا شائع شدہ id، اس وقت بھی جب آپ نے alias یا کوئی دوسرا ہجے بھیجا ہو۔
`choices`	`array`	ہمیشہ ایک اندراج، جس کا `index` 0 ہے۔
`choices[0].message.role`	`string`	ہمیشہ `assistant`۔
`choices[0].message.content`	`string \| null`	جواب۔ جب جواب میں `tool_calls` ہوں تو یہ `null` ہو سکتا ہے۔
`choices[0].message.reasoning_content`	`string \| null`	جواب سے پہلے ماڈل کی reasoning، یا `null` جب کوئی نہ ہو۔
`choices[0].message.tool_calls`	`array`	صرف تب موجود ہوتا ہے جب ماڈل آپ کے بیان کیے ہوئے ٹولز میں سے کوئی کال کرے۔
`choices[0].finish_reason`	`string`	جواب کے لیے `stop`، اور جب ماڈل ٹول کال کرے تو `tool_calls`۔
`usage.prompt_tokens`	`integer`	وہ ٹوکنز جو ماڈل نے اس جواب کے لیے پڑھے۔ `shannon-2-*` اور Shannon 3 فیملی پر یہ آپ کے بھیجے ہوئے متن سے زیادہ ہو سکتے ہیں۔
`usage.completion_tokens`	`integer`	وہ ٹوکنز جو ماڈل نے لکھے۔
`usage.total_tokens`	`integer`	کل۔ Shannon ماڈل کا چارج اسی عدد سے نکالا جاتا ہے۔

usage ٹوکنز کی گنتی رکھتا ہے، رقم نہیں۔ کال نے آپ کے بیلنس سے کیا لیا، یہ Keys & usage پر فی درخواست دکھایا جاتا ہے؛ اس کا حساب کیسے ہوتا ہے، یہ حدود اور بیلنس صفحے پر ہے۔ حدود اور بیلنس
ہر جواب، ایرر اور سٹریم سمیت، میں ہیڈر x-request-id ہوتا ہے۔ اگر آپ کی درخواست میں x-request-id ہیڈر ہو تو اس کی قدر واپس آتی ہے؛ ورنہ قدر 12 ہیکسا ڈیسیمل حروف ہوتی ہے۔ اسے اپنے لاگز میں رکھیں: یہ اسی ایک درخواست کا نام ہے۔

وہی کال سٹریم کے طور پر

جواب کو لکھے جانے کے ساتھ پڑھنے کے لیے stream کو true پر سیٹ کریں۔ درخواست میں باقی سب کچھ وہی رہتا ہے۔

from openai import OpenAI

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

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

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

import OpenAI from 'openai';

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

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

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}

curl -N -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!"}
    ],
    "max_tokens": 1024,
    "stream": true
  }'

سٹریم کا ہر فریم ایک لائن ہے جو data: سے شروع ہوتی ہے اور JSON آبجیکٹ رکھتی ہے۔ ایک فریم، کئی لائنوں میں چھاپا ہوا:

ایک فریم

{
  "id": "chatcmpl-9b2f6c1e4a7d4f0f8a3c5d2e1b6a7c90",
  "object": "chat.completion.chunk",
  "created": 1791590400,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "Hello! "
      },
      "finish_reason": null
    }
  ]
}

فریمز، ترتیب سے	delta	finish_reason
جب ماڈل reasoning کر رہا ہو۔ صفر یا زیادہ فریمز۔	`{"reasoning_content": "…"}`	`null`
جواب، ٹکڑا ٹکڑا۔ صفر یا زیادہ فریمز۔	`{"content": "…"}`	`null`
آخری JSON فریم۔ اس میں `usage` بھی ہوتا ہے؛ آپ کو اسے مانگنے کی ضرورت نہیں۔	`{}`	`"stop"`
سٹریم کا اختتام: لائن `data: [DONE]`۔

جواب کا اسٹیٹس 200 اور content-type: text/event-stream ہے۔ ہر فریم ایک لائن data: <json> ہے جس کے بعد ایک خالی لائن ہوتی ہے۔
لائن : ping ہر 15 سیکنڈ بعد آتی ہے۔ یہ ایک تبصرہ ہے جو کنکشن کھلا رکھتا ہے؛ SSE کلائنٹس اسے چھوڑ دیتے ہیں۔
سٹریم کھلنے کے بعد کی ناکامی data: {"error": {…}} فریم کے طور پر آتی ہے۔ اسٹیٹس 200 ہی رہتا ہے، اس لیے فریمز کو جانچیں۔

اسٹریمنگ

اگر کال ناکام ہو

ایرر ایک JSON آبجیکٹ ہے جس میں error ہوتا ہے جو type اور message رکھتا ہے۔ یہ وہ جوابات ہیں جن سے پہلی کال کا سب سے زیادہ واسطہ پڑتا ہے۔

اسٹیٹس	قسم	پیغام	اس کا مطلب
`401`	`authentication_error`	`Missing authentication`	API تک کوئی کلید نہیں پہنچی۔ `Authorization: Bearer` اور اس کے بعد اپنی کلید بھیجیں۔
`401`	`authentication_error`	`Invalid API key`	کلید کسی اکاؤنٹ کی موجودہ کلید نہیں ہے۔ اسے Keys & usage سے دوبارہ کاپی کریں۔
`400`	`invalid_request_error`	`unknown model: <id>`	`model` شائع شدہ id نہیں ہے۔ ماڈلز اور قیمتیں سے کوئی id استعمال کریں۔
`422`	`invalid_request_error`	`Failed to deserialize the JSON body into the target type…`	کسی فیلڈ کی JSON قسم غلط ہے، یا `messages` غائب ہے۔
`429`	`rate_limit_error`	`Quota exceeded. Upgrade your plan at shannon-ai.com/plan`	درخواست کا آؤٹ پٹ بجٹ آپ کے بیلنس میں نہیں سماتا۔

غلطیاں

آگے کہاں جائیں

ماڈلز اور قیمتیں — ماڈل چنیں: ids، کانٹیکسٹ ونڈوز اور قیمتیں۔
Chat Completions — جس endpoint کو آپ نے کال کیا اس کا ہر درخواست فیلڈ، جواب فیلڈ اور سٹریم ایونٹ۔
اسٹریمنگ — سٹریم کے فریمز، keep-alive لائنیں اور سٹریم کے اندر ایررز۔
فنکشن کالنگ — ماڈل کو اپنے فنکشنز کال کرنے دیں۔
حدود اور بیلنس — درخواست کیا محفوظ کرتی ہے اور اس پر کتنا خرچ آتا ہے، اور آپ کتنی درخواستیں بھیج سکتے ہیں۔
API پلے گراؤنڈ — اپنی کلید سے براؤزر میں درخواستیں آزمائیں۔