Lêgerîna webê

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 بوارەکە لە ئاستی سەرەوەی body دایە، لەتەنیشت model و messages:

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

داواکارییەکی گەڕاو چی دەکات

• API بۆ دوایین نامەی بەکارهێنەر لە وێب دەگەڕێت. نۆرە پێشووەکانی گفتوگۆکە context ـی گەڕانەکە دەدەن.
• گەڕانەکە لەسەر هەر داواکارییەک جێبەجێ دەبێت کە web_search: true دەنێرێت. مۆدێلەکە بڕیار نادات بگەڕێت یان نا.
• ئەنجامەکان وەک سەرچاوەی ژمارەدار دەخرێنە بەردەم مۆدێلەکە، و مۆدێلەکە وەڵامەکەی لەوانەوە دەنووسێت.
• وەڵامەکە کاتێک دەست پێدەکات گەڕانەکە تەواو بێت. داواکارییەکی stream کراو هیچ نانێرێت، نە headers و نە ڕووداو، تا ئەو کات، بۆیە چاوەڕێکردنێکی درێژتر پێش یەکەم chunk لەبەرچاو بگرە.

وەڵامەکە چی هەڵدەگرێت

• وەڵامەکە شێوەی ئاسایی endpoint ـەکەی هەیە. وەڵامەکە لە choices[0].message.content دایە (بلۆکی text لەسەر /v1/messages).
• دەقەکە دەتوانێت نیشانەی وەک [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 دا دێن دەستبەجێ پێش دوایینەکە، وەک delta.annotations.
• sources تەنها کاتێک هەیە کە گەڕانی ئەم داواکارییە شتێکی دۆزیبێتەوە. وەڵامێک بەبێ ئەوە بەبێ ئەنجامی گەڕان نووسراوە.

گەڕانەکان چۆن هەژمار دەکرێن

هەر پلانێک ژمارەیەک گەڕان بۆ هەر ڕۆژێک لەخۆدەگرێت:

• داواکارییەک کە گەڕانەکەی شتێکی دۆزیبێتەوە یەک گەڕان لە ڕێپێدانی ڕۆژەکە بەکاردەهێنێت. گەڕانێک کە هیچی نەدۆزیبێتەوە هیچ بەکارناهێنێت.
• Chat و API ڕێپێدانی ئەو هەژمارە هاوبەش دەکەن کە خاوەنی کلیلەکەیە.
• ژماردنەکە هەموو ڕۆژێک لە 00:00 UTC دەست پێدەکاتەوە.
• ئەنجامەکانی گەڕان تۆکنی input ی داواکارییەکەن و لەگەڵ ماوەی prompt نرخ دەگیرێن.

پلانەکان بەراورد بکە

کاتێک گەڕانەکانی ڕۆژەکە تەواو دەبن

داواکارییەک کە web_search: true دەنێرێت دوای دوایین گەڕانی ڕۆژەکە ڕەت ناکرێتەوە. بەبێ گەڕان وەڵام دەدرێتەوە: status 200 ە و وەڵامەکە sources ی نییە.

گەڕان وەک ئامرازی خۆت

web_search: true تاکە گۆڕەری ئەو گەڕانەیە کە لێرە باس کراوە. function ێک کە لە tools دا پێناسەی دەکەیت و ناوی دەنێیت web_search یەکێکە لە ئامرازەکانی خۆت: مۆدێلەکە بانگکردنێک دەگەڕێنێتەوە، و کۆدەکەت گەڕانەکە جێبەجێ دەکات و ئەنجامەکە دەگەڕێنێتەوە.

جۆرەکانی ئامرازی گەڕانی پلاتفۆڕمەکانی دیکە، وەک web_search_20250305 لەسەر /v1/messages یان {"type": "web_search"} لەسەر /v1/responses، لێرە گەڕان دەست پێناکەن.

هەڵەکان

گەڕانی وێب هیچ کۆدی status و هیچ جۆری هەڵە زیاد ناکات. گەڕانێک کە هیچ نەدۆزێتەوە، یان ڕۆژێک بەبێ گەڕانی ماوە، وەڵامێکی ئاسایی دەدات بەبێ ئەنجامی گەڕان. هەموو هەڵەیەکی دیکە وەک داواکارییەک بەبێ گەڕان وایە. Çewtî