Web search

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

Ang reply ay karaniwang chat completion na may dalawang dagdag. Itinuturo ng sagot ang mga resulta ng search gamit ang mga numero sa square bracket, sinasabi ng sources kung ano ang kinakatawan ng bawat numero, at minamarkahan ng annotations kung saan sinisipi ang bawat isa:

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

Pag-on ng search

Ang search ay isang field ng request, naka-off by default. Walang sine-search maliban kung ipinapadala ito ng request.

Sa /v1/messages, nasa pinakamataas na antas ng body ang field, katabi ng model at messages:

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

Ano ang ginagawa ng request na may search

• Nagse-search ang API sa web para sa huling user message. Ang mga naunang turn ng conversation ang nagbibigay ng context sa search.
• Tumatakbo ang search sa bawat request na nagpapadala ng web_search: true. Hindi pinipili ng model kung magse-search.
• Inilalagay sa harap ng model ang mga resulta bilang may bilang na mga source, at isinusulat ng model ang sagot nito mula sa mga iyon.
• Nagsisimula ang reply kapag tapos na ang search. Ang naka-stream na request ay walang ipinapadala, ni header ni event, hanggang noon, kaya maglaan ng mas mahabang paghihintay bago ang unang chunk.

Ano ang laman ng reply

• Ang reply ay may karaniwang hugis ng endpoint nito. Ang sagot ay nasa choices[0].message.content (isang text block sa /v1/messages).
• Ang text ay maaaring may mga marker gaya ng [1] at [2] pagkatapos ng mga pahayag na sinusuportahan nila. Bawat numero ay kumakatawan sa isa sa mga resultang binasa ng model.
• Pinangangalanan ng sources ang mga resultang iyon: isang entry para sa bawat resultang ibinigay sa model, na may index, title at url. Ang marker na [1] ay ang entry na may index na 1. Nakalista rin ang mga resultang hindi sinipi ng sagot.
• Sa /v1/chat/completions, may annotations din ang message, sa hugis ng OpenAI: isang url_citation para sa bawat source na pinangalanan ng isang marker, na may url, title, at start_index at end_index, ang posisyon ng marker sa content na binibilang sa mga character (hindi kasama ang dulo).
• Sa isang stream, kasama ng huling chunk ang sources, at sa /v1/messages ay kasama ito ng event na message_delta. Dumarating ang mga annotation sa isang chunk bago mismo ang huli, bilang delta.annotations.
• Naroon lang ang sources kung may nakita ang search ng request na ito. Ang reply na wala nito ay isinulat nang walang mga resulta ng search.

Paano binibilang ang mga search

Bawat plan ay may kasamang bilang ng search kada araw:

• Ang request na may nakitang resulta ang search ay gumagamit ng isang search mula sa allowance ng araw. Ang search na walang nakita ay walang ginagamit.
• Pinaghahatian ng chat at API ang allowance ng account na nagmamay-ari ng key.
• Nagsisimula ulit ang bilang araw-araw sa 00:00 UTC.
• Ang mga resulta ng search ay input tokens ng request at sinisingil kasama ng natitirang prompt.

Ihambing ang mga plan

Kapag naubos ang mga search ng araw

Ang request na nagpapadala ng web_search: true pagkatapos ng huling search ng araw ay hindi tinatanggihan. Sinasagot ito nang walang search: 200 ang status at walang sources ang reply.

Search bilang sarili mong tool

Ang web_search: true ang tanging switch ng search na inilalarawan dito. Ang function na dinedefine mo sa tools at pinangalanang web_search ay isa sa sarili mong mga tool: nagbabalik ang model ng call, at pinapatakbo ng iyong code ang search at ipinapadala pabalik ang resulta.

Ang mga search tool type ng ibang platform, gaya ng web_search_20250305 sa /v1/messages o {"type": "web_search"} sa /v1/responses, ay hindi nagsisimula ng search dito.

Mga error

Walang idinaragdag na status code at error type ang web search. Ang search na walang nakita, o araw na wala nang natitirang search, ay nagbibigay ng karaniwang sagot na walang resulta ng search. Pareho ng sa request na walang search ang bawat ibang error. Paghawak ng Error