Căutare web integrată

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

Răspunsul este un chat completion obișnuit, cu două adăugiri. Răspunsul trimite la rezultatele căutării cu numere între paranteze drepte, sources spune ce reprezintă fiecare număr, iar annotations marchează unde este citat fiecare:

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

Pornirea căutării

Căutarea este un câmp al cererii, oprit implicit. Nu se caută nimic dacă o cerere nu îl trimite.

Pe /v1/messages, câmpul stă la nivelul de sus al corpului, lângă model și messages:

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

Ce face o cerere cu căutare

• API-ul caută pe web ultimul mesaj al utilizatorului. Rundele anterioare ale conversației dau căutării contextul.
• Căutarea rulează la fiecare cerere care trimite web_search: true. Modelul nu alege dacă caută.
• Rezultatele sunt puse în fața modelului ca surse numerotate, iar modelul își scrie răspunsul pornind de la ele.
• Răspunsul începe când căutarea s-a terminat. O cerere cu streaming nu trimite nimic, nici header-e, nici evenimente, până atunci, deci prevede o așteptare mai lungă înainte de primul chunk.

Ce conține răspunsul

• Răspunsul are forma obișnuită a endpoint-ului său. Răspunsul se află în choices[0].message.content (un bloc text pe /v1/messages).
• Textul poate conține marcaje precum [1] și [2] după afirmațiile pe care le susțin. Fiecare număr reprezintă unul dintre rezultatele citite de model.
• sources numește aceste rezultate: câte o intrare pentru fiecare rezultat dat modelului, cu index, title și url. Marcajul [1] este intrarea cu index 1. Sunt listate și rezultatele pe care răspunsul nu le citează.
• Pe /v1/chat/completions, mesajul are și annotations, în forma OpenAI: câte un url_citation pentru fiecare sursă numită de un marcaj, cu url, title, precum și start_index și end_index, poziția marcajului în content numărată în caractere (sfârșitul nu este inclus).
• Într-un stream, sources vine cu ultimul chunk, iar pe /v1/messages cu evenimentul message_delta. Adnotările vin într-un chunk chiar înaintea ultimului, ca delta.annotations.
• sources există doar atunci când căutarea acestei cereri a găsit ceva. Un răspuns fără el a fost scris fără rezultate de căutare.

Cum sunt numărate căutările

Fiecare plan include un număr de căutări pe zi:

• O cerere a cărei căutare a găsit ceva consumă o căutare din cota zilei. O căutare care nu a găsit nimic nu consumă nicio căutare.
• Chatul și API-ul folosesc împreună cota contului căruia îi aparține cheia.
• Numărătoarea pornește din nou în fiecare zi la 00:00 UTC.
• Rezultatele căutării sunt token-uri de intrare ale cererii și sunt taxate împreună cu restul prompt-ului.

Compară planurile

Când căutările zilei s-au terminat

O cerere care trimite web_search: true după ultima căutare a zilei nu este refuzată. Primește răspuns fără căutare: statusul este 200, iar răspunsul nu are sources.

Căutarea ca instrument propriu

web_search: true este singurul comutator al căutării descrise aici. O funcție pe care o definești în tools și o numești web_search este unul dintre instrumentele tale: modelul returnează un apel, iar codul tău rulează căutarea și trimite rezultatul înapoi.

Tipurile de instrumente de căutare ale altor platforme, precum web_search_20250305 pe /v1/messages sau {"type": "web_search"} pe /v1/responses, nu pornesc o căutare aici.

Erori

Căutarea web nu adaugă niciun cod de status și niciun tip de eroare. O căutare care nu găsește nimic sau o zi fără căutări rămase dă un răspuns normal, fără rezultate de căutare. Orice altă eroare este aceeași ca pentru o cerere fără căutare. Gestionare erori