Pencarian Web Terintegrasi

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

Balasan adalah chat completion biasa dengan dua tambahan. Jawaban merujuk ke hasil pencarian dengan angka dalam tanda kurung siku, sources menyatakan apa yang diwakili tiap angka, dan annotations menandai di mana masing-masing dikutip:

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

Mengaktifkan pencarian

Pencarian adalah field permintaan, mati secara bawaan. Tidak ada yang dicari kecuali permintaan mengirimnya.

Pada /v1/messages, field berada di level teratas body, di samping model dan messages:

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

Apa yang dilakukan permintaan dengan pencarian

• API mencari di web untuk pesan user terakhir. Giliran percakapan sebelumnya memberi konteks pada pencarian.
• Pencarian berjalan pada setiap permintaan yang mengirim web_search: true. Model tidak memilih apakah akan mencari.
• Hasil diletakkan di depan model sebagai sumber bernomor, dan model menulis jawabannya dari sumber itu.
• Balasan dimulai ketika pencarian selesai. Permintaan dengan stream tidak mengirim apa pun, baik header maupun event, sampai saat itu, jadi sediakan waktu tunggu yang lebih lama sebelum chunk pertama.

Isi balasan

• Balasan memiliki bentuk umum endpoint-nya. Jawaban ada di choices[0].message.content (blok text pada /v1/messages).
• Teks dapat membawa penanda seperti [1] dan [2] setelah pernyataan yang didukungnya. Setiap angka mewakili salah satu hasil yang dibaca model.
• sources menyebutkan hasil-hasil itu: satu entri untuk setiap hasil yang diberikan kepada model, dengan index, title, dan url. Penanda [1] adalah entri dengan index 1. Hasil yang tidak dikutip oleh jawaban juga dicantumkan.
• Pada /v1/chat/completions, pesan juga memiliki annotations, dalam bentuk OpenAI: satu url_citation untuk setiap sumber yang disebut oleh penanda, dengan url, title, serta start_index dan end_index, yaitu posisi penanda di content yang dihitung dalam karakter (posisi akhir tidak termasuk).
• Dalam stream, sources datang bersama chunk terakhir, dan pada /v1/messages bersama event message_delta. Anotasi datang dalam satu chunk tepat sebelum chunk terakhir, sebagai delta.annotations.
• sources hanya ada jika pencarian pada permintaan ini menemukan sesuatu. Balasan tanpa field ini ditulis tanpa hasil pencarian.

Cara pencarian dihitung

Setiap paket menyertakan sejumlah pencarian per hari:

• Permintaan yang pencariannya menemukan sesuatu memakai satu pencarian dari kuota hari itu. Pencarian yang tidak menemukan apa pun tidak memakai kuota.
• Chat dan API berbagi kuota akun pemilik kunci.
• Hitungan dimulai lagi setiap hari pukul 00:00 UTC.
• Hasil pencarian adalah token input permintaan dan ditagih bersama sisa prompt.

Bandingkan paket

Ketika pencarian hari itu habis

Permintaan yang mengirim web_search: true setelah pencarian terakhir hari itu tidak ditolak. Permintaan dijawab tanpa pencarian: statusnya 200 dan balasan tidak memiliki sources.

Pencarian sebagai tool Anda sendiri

web_search: true adalah satu-satunya sakelar pencarian yang dijelaskan di sini. Fungsi yang Anda definisikan di tools dan beri nama web_search adalah salah satu tool Anda sendiri: model mengembalikan panggilan, dan kode Anda menjalankan pencarian lalu mengirim hasilnya kembali.

Tipe tool pencarian dari platform lain, seperti web_search_20250305 pada /v1/messages atau {"type": "web_search"} pada /v1/responses, tidak memulai pencarian di sini.

Error

Pencarian web tidak menambah kode status maupun tipe error. Pencarian yang tidak menemukan apa pun, atau hari tanpa sisa pencarian, memberi jawaban biasa tanpa hasil pencarian. Setiap error lainnya sama seperti pada permintaan tanpa pencarian. Penanganan kesalahan