جوړ شوی ویب لټون

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": "What is the weather forecast for Lisbon this weekend?"}],
    extra_body={"web_search": True},  # a Shannon field, so it goes in extra_body
)

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: "What is the weather forecast for Lisbon this weekend?" }],
  web_search: true,
});

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

curl 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": "What is the weather forecast for Lisbon this weekend?"}
    ],
    "web_search": true
  }'

ځواب عادي chat completion دی چې دوه اضافې لري. ځواب د مربع قوسونو په شمیرو سره د لټون پایلو ته اشاره کوي، sources وايي چې هره شمیره د څه استازیتوب کوي، او annotations نښه کوي چې هر یو چېرته یاد شوی:

{
  "id": "chatcmpl-3e5a7c9b1d2f4a6c8e0b2d4f6a8c1e3b",
  "object": "chat.completion",
  "created": 1791590400,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Saturday in Lisbon is forecast to be sunny with a high near 24 °C [1]. Sunday turns cloudy, with a chance of light rain in the afternoon [2].",
        "reasoning_content": null,
        "annotations": [
          {
            "type": "url_citation",
            "url_citation": {
              "start_index": 66,
              "end_index": 69,
              "url": "https://weather.example/lisbon/weekend",
              "title": "Lisbon weather: weekend outlook"
            }
          },
          {
            "type": "url_citation",
            "url_citation": {
              "start_index": 137,
              "end_index": 140,
              "url": "https://forecast.example/pt/lisbon/sunday",
              "title": "Sunday forecast for Lisbon"
            }
          }
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 2874,
    "completion_tokens": 41,
    "total_tokens": 2915
  },
  "sources": [
    {
      "index": 1,
      "title": "Lisbon weather: weekend outlook",
      "url": "https://weather.example/lisbon/weekend"
    },
    {
      "index": 2,
      "title": "Sunday forecast for Lisbon",
      "url": "https://forecast.example/pt/lisbon/sunday"
    },
    {
      "index": 3,
      "title": "Portugal: the week ahead",
      "url": "https://news.example/portugal/weather-week"
    }
  ]
}

لټون چالانول

لټون د غوښتنې ساحه ده، په ډیفالټ بنده. هیڅ نه لټول کیږي مګر دا چې غوښتنه یې ولیږي.

په /v1/messages کې ساحه د بدنې په پورتنۍ کچه کې ده، د model او messages تر څنګ:

{
  "model": "shannon-3",
  "web_search": true,
  "messages": [
    {
      "role": "user",
      "content": "What is the weather forecast for Lisbon this weekend?"
    }
  ]
}

لټون شوې غوښتنه څه کوي

• API د وروستي user message لپاره په ویب کې لټوي. د ګفتګې پخواني turns لټون ته خپل شرایط ورکوي.
• لټون په هره غوښتنه چلیږي چې web_search: true لیږي. ماډل نه غوره کوي چې ولټوي که نه.
• پایلې د شمیرل شوو سرچینو په توګه ماډل مخې ته ږدل کیږي، او ماډل خپل ځواب له دوی لیکي.
• ځواب هغه وخت پیلیږي کله چې لټون پای ته ورسیږي. stream شوې غوښتنه تر هغه هیڅ نه لیږي، نه headers او نه رخدادونه، نو د لومړي chunk مخکې اوږد انتظار ته چمتو اوسئ.

ځواب څه لري

• ځواب د خپل endpoint معمول بڼه لري. ځواب په choices[0].message.content کې دی (په /v1/messages کې text block).
• متن کولی شي نښې لکه [1] او [2] د هغو بیاناتو وروسته ولري چې ملاتړ یې کوي. هر شمیره د هغو پایلو یوه استازیتوب کوي چې ماډل لوستلې.
• sources دغه پایلې نومولي: د هرې هغې پایلې لپاره یو ننوتنه چې ماډل ته ورکړل شوې، د index، title او url سره. نښه [1] هغه ننوتنه ده چې index یې 1 دی. هغه پایلې هم لیست شوي چې ځواب یې نه یادوي.
• په /v1/chat/completions کې پیغام annotations هم لري، د OpenAI په بڼه: د هرې سرچینې لپاره یو url_citation چې یوه نښه یې نوم اخلي، د url، title، او start_index او end_index سره، چې په content کې د نښې ځای دی او په توریو شمیرل کیږي (پای پکې نه شامليږي).
• په stream کې sources د وروستي chunk سره راځي، او په /v1/messages کې د message_delta پیښې سره. annotations د وروستي chunk څخه سمدستي مخکې په یوه chunk کې د delta.annotations په توګه راځي.
• sources یوازې هغه وخت شته چې د دې غوښتنې لټون یو څه موندلي وي. هغه ځواب چې دا نه لري د لټون پایلو پرته لیکل شوی.

لټونونه څنګه شمیرل کیږي

هر پلان په ورځ کې د لټونونو شمیر لري:

• هغه غوښتنه چې لټون یې څه وموندل د ورځې له اجازې یو لټون کاروي. لټون چې هیڅ ونه موند هیڅ نه کاروي.
• چیټ او API د هغه حساب اجازه شریکوي چې کیلي یې لري.
• شمېرنه هره ورځ په 00:00 UTC بیا پیلیږي.
• د لټون پایلې د غوښتنې input ټوکنونه دي او د prompt له پاتې برخې سره بیل کیږي.

پلانونه پرتله کړئ

کله چې د ورځې لټونونه ختم شي

هغه غوښتنه چې web_search: true لیږي وروسته له دې چې د ورځې وروستی لټون کارول شوی وي رد نه کیږي. دا پرته له لټون ځواب کیږي: حالت 200 دی او ځواب sources نه لري.

لټون د خپل tool په توګه

web_search: true دلته د بیان شوي لټون یوازینی سویچ دی. function چې تاسو په tools کې تعریفوئ او web_search یې نوموئ ستاسو یو خپل tool دی: ماډل call بیرته ورکوي، او ستاسو کوډ لټون چلوي او پایله بیرته لیږي.

د نورو پلاتفورمونو د لټون tool ډولونه، لکه په /v1/messages کې web_search_20250305 یا په /v1/responses کې {"type": "web_search"}، دلته لټون نه پیلوي.

تېروتنې

Web search هیڅ حالت کوډ او هیڅ د تېروتنې ډول نه زیاتوي. لټون چې هیڅ ونه موند، یا ورځ چې لټونونه نه پاتې وي، عادي ځواب پرته له لټون پایلو ورکوي. هره بله تېروتنه هماغه ده لکه د غوښتنې لپاره پرته له لټون. د تېروتنې اداره کول