Ugrađena web pretraga

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
  }'

Odgovor je obično čet dopunjavanje sa dva dodatka. Odgovor upućuje na rezultate pretrage brojevima u uglastim zagradama, sources kaže šta svaki broj označava, a annotations obeležava gde se svaki od njih navodi:

{
  "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"
    }
  ]
}

Uključivanje pretrage

Pretraga je polje zahteva, podrazumevano isključeno. Ništa se ne pretražuje osim ako je zahtev ne pošalje.

Na /v1/messages polje stoji na najvišem nivou tela, pored model i messages:

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

Šta radi zahtev sa pretragom

• API pretražuje web za poslednju korisničku poruku. Raniji potezi razgovora daju pretrazi kontekst.
• Pretraga se izvršava na svakom zahtevu koji šalje web_search: true. Model ne bira da li će pretraživati.
• Rezultati se stavljaju pred model kao numerisani izvori, a model piše odgovor na osnovu njih.
• Odgovor počinje kada je pretraga gotova. Zahtev sa streamom do tada ne šalje ništa, ni zaglavlja ni događaje, zato računajte na duže čekanje pre prvog dela.

Šta odgovor sadrži

• Odgovor ima uobičajeni oblik svog endpointa. Odgovor je u choices[0].message.content (blok text na /v1/messages).
• Tekst može da nosi oznake kao što su [1] i [2] posle tvrdnji koje podržavaju. Svaki broj označava jedan od rezultata koje je model pročitao.
• sources imenuje te rezultate: jedan unos za svaki rezultat koji je dat modelu, sa index, title i url. Oznaka [1] je unos sa index 1. Navedeni su i rezultati koje odgovor ne navodi.
• Na /v1/chat/completions poruka ima i annotations, u OpenAI obliku: jedan url_citation za svaki izvor koji imenuje neka oznaka, sa url, title, kao i start_index i end_index, pozicijom oznake u content izbrojanom u znakovima (kraj nije uključen).
• U streamu sources stiže sa poslednjim delom, a na /v1/messages sa događajem message_delta. Annotations stižu u jednom delu odmah pre poslednjeg, kao delta.annotations.
• sources postoji samo ako je pretraga ovog zahteva nešto našla. Odgovor bez njega napisan je bez rezultata pretrage.

Kako se pretrage računaju

Svaki plan uključuje određen broj pretraga dnevno:

• Zahtev čija je pretraga nešto našla troši jednu pretragu dnevne dozvole. Pretraga koja nije našla ništa ne troši nijednu.
• Čet i API dele dozvolu naloga koji poseduje ključ.
• Brojanje počinje iznova svakog dana u 00:00 UTC.
• Rezultati pretrage su ulazni tokeni zahteva i naplaćuju se sa ostatkom prompta.

Uporedite planove

Kada se dnevne pretrage potroše

Zahtev koji šalje web_search: true posle poslednje pretrage u danu ne odbija se. Odgovara mu se bez pretrage: status je 200, a odgovor nema sources.

Pretraga kao vaš alat

web_search: true je jedini prekidač pretrage opisane ovde. Funkcija koju definišete u tools i nazovete web_search je jedan od vaših alata: model vraća poziv, a vaš kod izvršava pretragu i šalje rezultat nazad.

Tipovi alata za pretragu drugih platformi, kao što su web_search_20250305 na /v1/messages ili {"type": "web_search"} na /v1/responses, ovde ne pokreću pretragu.

Greške

Web pretraga ne dodaje statusni kod ni tip greške. Pretraga koja ne nađe ništa, ili dan bez preostalih pretraga, daje običan odgovor bez rezultata pretrage. Svaka druga greška ista je kao za zahtev bez pretrage. Upravljanje greškama