Langkau ke kandungan
Format Antropik

Format Antropik

POST /v1/messages menerima permintaan dalam format Anthropic Messages dan menjawab dalam format yang sama, secara stream atau tidak. Gunakannya dengan SDK Anthropic dan alat yang dibina di atasnya, seperti Claude Code: tetapkan base URL, gunakan kunci API Shannon anda dan namakan id model Shannon.

POST https://api.shannon-ai.com/v1/messages

Halakan SDK Anthropic ke base URL Shannon. SDK menambah /v1/messages dan menghantar kunci anda dalam header x-api-key.

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com",
)

message = client.messages.create(
    model="shannon-3",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

Balasan ialah mesej yang contentnya ialah senarai blok. Cari blok mengikut typenya: apabila model bernalar, blok pertama ialah thinking dan teks datang selepasnya.

200 JSON
{
  "id": "msg_5f0c1e7a9b3d4c62a8e1f07d2b46c9a3",
  "type": "message",
  "role": "assistant",
  "model": "shannon-3",
  "content": [
    {
      "type": "thinking",
      "thinking": "The user wants a greeting in one sentence. Keep it short and friendly."
    },
    {
      "type": "text",
      "text": "Hello, it is good to meet you."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 1184,
    "output_tokens": 46
  }
}

Header

Header Nilai Penerangan
x-api-key YOUR_API_KEY Kunci API anda. Authorization: Bearer YOUR_API_KEY diterima sebagai gantinya.
content-type application/json Diperlukan.
anthropic-version 2023-06-01 Diterima, tidak diperlukan. SDK Anthropic menghantar 2023-06-01; balasan mempunyai format yang sama walau apa pun nilainya.
anthropic-beta Diterima, tidak diperlukan.
x-request-id Pilihan. Id anda sendiri untuk permintaan. Ia dikembalikan tanpa perubahan pada balasan; tanpanya balasan membawa id 12 aksara heksadesimal.

Medan permintaan

Hanya messages yang diperlukan. Lajur Dilaksanakan oleh menamakan model yang balasannya diubah oleh sesuatu medan. Model open-weight yang dihoskan ialah dua belas id dalam senarai model; keluarga Shannon 3 ialah shannon-3, shannon-3-pro, shannon-3.1 dan shannon-3.1-pro. Model & harga

Medan Jenis Lalai Penerangan Dilaksanakan oleh
model string shannon-1.6-lite Id model Shannon daripada senarai model. Hantar dengan setiap permintaan. Padanan tidak sensitif huruf besar-kecil. Sebarang nama lain memulangkan 400 unknown model, jadi alat yang menghantar nama modelnya sendiri perlu ditetapkan kepada id Shannon. Semua model
messages array Diperlukan. Perbualan, mesej tertua dahulu, dengan peranan user dan assistant. Lihat Mesej dan blok kandungan di bawah. Semua model
system string | array Arahan untuk model: rentetan, atau tatasusunan blok teks. Lihat System prompt di bawah. Model open-weight yang dihoskan, shannon-1.6-*, shannon-2-*, shannon-coder-1
max_tokens integer 4096 Had atas balasan, dalam token. Pilihan pada endpoint ini; SDK Anthropic sentiasa menghantarnya. Nilai di luar 1 hingga 65,536 dialihkan ke dalam julat itu. Ia juga jumlah yang diketepikan daripada baki anda semasa permintaan berjalan. Model open-weight yang dihoskan, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
stream boolean false true menghantar balasan sebagai server-sent events. Lihat Streaming di bawah. Semua model
temperature number Suhu persampelan. Pada model open-weight yang dihoskan nilai dikekalkan antara 0 dan 2. Model open-weight yang dihoskan, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1
top_p number Persampelan nukleus. Model open-weight yang dihoskan
stop_sequences array Sehingga 4 rentetan. Jawapan berakhir sebelum yang pertama muncul. stop_reason kekal end_turn. Model open-weight yang dihoskan
tools array Alat yang boleh dipanggil oleh model, masing-masing sebagai {"name", "description", "input_schema"}. Lihat Tools di bawah. Semua model
tool_choice object {"type": "auto"} membiarkan model memutuskan, {"type": "any"} membuatnya memanggil alat, {"type": "tool", "name": "…"} membuatnya memanggil alat itu. Model open-weight yang dihoskan
thinking object Sejauh mana model bernalar sebelum menjawab. Lihat Thinking di bawah. Model open-weight yang dihoskan
web_search boolean false Tambahan Shannon pada format ini: true membenarkan model mencari di web sebelum menjawab. shannon-1.6-*, shannon-2-*, keluarga Shannon 3

Tanpa max_tokens nilainya ialah 4,096, dan 65,536 pada shannon-coder-1.

Penanda metadata, top_k, service_tier dan cache_control pada blok diterima supaya kod klien sedia ada berjalan tanpa perubahan. Ia tidak mengubah balasan; caching prompt pada model open-weight yang dihoskan adalah automatik.

Jawapan JSON mengikut skema diminta dengan response_format pada Chat Completions dan dengan text.format pada Responses. Output Berstruktur

Permintaan dengan system prompt dan thinking

Permintaan ini menghantar system prompt, bajet thinking, suhu dan jujukan henti. Ia menggunakan model open-weight yang dihoskan, yang melaksanakan kesemuanya.

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com",
)

message = client.messages.create(
    model="DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    max_tokens=4096,
    system="You are a physics teacher. Answer in two sentences.",
    thinking={"type": "enabled", "budget_tokens": 2048},
    temperature=0.3,
    stop_sequences=["\n\n"],
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
)

for block in message.content:
    if block.type == "thinking":
        print("reasoning:", block.thinking)
    elif block.type == "text":
        print("answer:", block.text)
print(message.usage)

Pada model open-weight yang dihoskan, usage melaporkan token yang dibaca daripada cache prompt secara berasingan daripada token input yang lain.

200 JSON
{
  "usage": {
    "input_tokens": 31,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "output_tokens": 62
  }
}

System prompt

system ialah rentetan, atau tatasusunan blok teks dalam bentuk [{"type": "text", "text": "…"}]. Teks blok-blok itu disambung dengan pemisah baris.

Ia dilaksanakan oleh model open-weight yang dihoskan, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro dan shannon-coder-1. Dengan id keluarga Shannon 3, letakkan arahan yang mesti dipatuhi dalam mesej pengguna.

Mesej dan blok kandungan

Sesebuah mesej mempunyai role, iaitu user atau assistant, dan content. content ialah rentetan, atau tatasusunan blok.

Blok Penerangan Tersedia pada
{"type": "text", "text": "…"} Teks. Semua model
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "…"}}
{"type": "image", "source": {"type": "url", "url": "…"}}
Imej dalam mesej user, sebagai base64 atau melalui URL. Keluarga Shannon 3, shannon-1.6-lite, shannon-1.6-pro, dan model open-weight yang dihoskan yang menyenaraikan input imej
{"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} Dokumen (PDF, Word, PowerPoint atau Excel) dalam mesej user, sebagai base64 atau melalui URL. Keluarga Shannon 3
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} Dalam mesej assistant: panggilan alat yang dibuat oleh model dalam balasan terdahulu. Semua model
{"type": "tool_result", "tool_use_id": "toolu_…", "content": "…"} Dalam mesej user: hasil panggilan itu. content ialah rentetan, atau senarai blok teks. Semua model

Anda boleh menghantar semula content sesuatu balasan terdahulu seperti sedia ada: blok text dan tool_use dibaca, blok thinking dilangkau.

Pada peringkat Shannon, imej dan dokumen dibaca daripada mesej user yang terakhir. Saiz dan had mempunyai halaman tersendiri. Imej dan fail

Thinking

Model open-weight yang dihoskan memetakan thinking kepada tahap usaha penaakulan. Tanpa medan ini tahap usahanya tinggi.

Bentuk budget_tokens Kesan
{"type": "disabled"} Tiada penaakulan. Balasan tidak mempunyai blok thinking.
{"type": "enabled", "budget_tokens": 2048} ≤ 2,048 Usaha rendah.
{"type": "enabled", "budget_tokens": 8192} ≤ 8,192 Usaha sederhana.
{"type": "enabled", "budget_tokens": 16000} > 8,192 Usaha tinggi.

Model yang bernalar memulangkan penaakulannya sebagai blok {"type": "thinking", "thinking": "…"} sebelum teks. Peringkat Shannon yang bernalar turut menghantarnya.

Tahap usaha diterangkan pada halaman tersendiri. Usaha penaakulan

Tools

Alat ialah fungsi yang dijalankan oleh kod anda. Terangkan setiap satu dengan name, description dan input_schema. Apabila model mahu menggunakan alat, balasan mengandungi blok tool_use dan stop_reason ialah tool_use.

Takrifan alat dalam tools:

tools
[
  {
    "name": "get_weather",
    "description": "Current weather for a city.",
    "input_schema": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string"
        }
      },
      "required": [
        "city"
      ]
    }
  }
]

content balasan yang memanggilnya:

200 content
[
  {
    "type": "text",
    "text": ""
  },
  {
    "type": "tool_use",
    "id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "name": "get_weather",
    "input": {
      "city": "Paris"
    }
  }
]

Jalankan alat, kemudian hantar permintaan sekali lagi dengan panggilan itu dan blok tool_result yang ditambah ke dalam messages:

messages
[
  {
    "role": "user",
    "content": "What is the weather in Paris?"
  },
  {
    "role": "assistant",
    "content": [
      {
        "type": "tool_use",
        "id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
        "name": "get_weather",
        "input": {
          "city": "Paris"
        }
      }
    ]
  },
  {
    "role": "user",
    "content": [
      {
        "type": "tool_result",
        "tool_use_id": "toolu_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
        "content": "{\"temperature_c\": 18, \"sky\": \"cloudy\"}"
      }
    ]
  }
]

tool_choice

Bentuk Kesan Dilaksanakan oleh
{"type": "auto"} Model memutuskan sama ada hendak memanggil alat. Ini ialah lalai. Semua model
{"type": "any"} Model mesti memanggil salah satu alat. Model open-weight yang dihoskan
{"type": "tool", "name": "…"} Model mesti memanggil alat yang dinamakan. Model open-weight yang dihoskan

Hanya alat yang mempunyai input_schema dibaca. Carian web bukan alat pada endpoint ini: tetapkan medan web_search.

Gelung alat diterangkan sepenuhnya pada halaman tersendiri. Panggilan Fungsi

Balasan

Medan Jenis Penerangan Dihantar oleh
id string msg_ diikuti 32 aksara heksadesimal. Semua model
type string Sentiasa message. Semua model
role string Sentiasa assistant. Semua model
model string Id kanonik model yang menjawab. Semua model
content array Blok balasan, mengikut urutan ini: thinking apabila model bernalar, text, kemudian satu tool_use bagi setiap panggilan alat. Semua model
stop_reason string Sebab balasan berakhir. Lihat nilai di bawah. Semua model
usage object input_tokens dan output_tokens. Semua model
sources array Hanya pada permintaan dengan web_search: true yang carian untuknya menemui sesuatu: hasil yang diberikan kepada model, setiap satu dengan index, title dan url. [1] dalam jawapan ialah entri dengan index 1. Dalam stream, ia datang bersama peristiwa message_delta. shannon-1.6-*, shannon-2-*, keluarga Shannon 3
usage.cache_read_input_tokens integer cache_read_input_tokens ialah bahagian prompt yang dibaca daripada cache; input_tokens ialah selebihnya. cache_creation_input_tokens sentiasa 0. Model open-weight yang dihoskan

Blok balasan

Blok Penerangan
{"type": "thinking", "thinking": "…"} Penaakulan model. Tiada ahli signature.
{"type": "text", "text": "…"} Teks jawapan. Ia boleh kosong apabila balasan ialah panggilan alat.
{"type": "tool_use", "id": "toolu_…", "name": "…", "input": {…}} Panggilan alat. input ialah objek JSON. Hantar hasilnya kembali dengan id yang sama.

stop_reason

stop_reason Penerangan Dihantar oleh
end_turn Model menamatkan jawapannya, atau salah satu daripada stop_sequences anda muncul. Semua model
tool_use Balasan mengandungi satu atau lebih panggilan alat. Semua model
max_tokens Balasan dipotong pada had output. Keluarga Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1, dalam stream

Streaming

Tetapkan stream kepada true untuk server-sent events. Setiap bingkai mempunyai baris event: dengan nama peristiwa dan baris data: dengan objek JSON yang mengulang nama itu dalam type. Pembantu stream SDK Anthropic membaca peristiwa ini untuk anda:

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com",
)

with client.messages.stream(
    model="shannon-3",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain server-sent events in three sentences."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    message = stream.get_final_message()

print()
print(message.stop_reason, message.usage)

Peristiwa, mengikut urutan ia tiba:

Peristiwa Data Bila
message_start message Sentiasa pertama. message mengandungi id, peranan, model, content kosong dan usage yang bermula dari sifar.
content_block_start index, content_block Satu blok dibuka. content_block ialah blok text atau thinking yang kosong, atau blok tool_use dengan id dan namenya.
content_block_delta index, delta {"type": "thinking_delta", "thinking"} Sebahagian penaakulan, untuk blok thinking.
content_block_delta index, delta {"type": "text_delta", "text"} Sebahagian jawapan, untuk blok text.
content_block_delta index, delta {"type": "input_json_delta", "partial_json"} Argumen panggilan alat, lengkap dalam satu delta, untuk blok tool_use.
content_block_stop index Blok dengan index ini sudah lengkap.
message_delta delta {stop_reason, stop_sequence}, usage Penghujung balasan: delta.stop_reason, dan usage permintaan.
message_stop Sentiasa terakhir.

Blok dinomborkan mengikut index dalam urutan ia dibuka, dan satu blok lengkap sebelum blok seterusnya dibuka. Baca setiap blok mengikut jenisnya, bukan nomborasnya: stream boleh membuka blok text kosong dahulu, kemudian blok thinking, dan menghantar jawapan dalam blok text yang kemudian.

200 text/event-stream
event: message_start
data: {"type":"message_start","message":{"id":"msg_5f0c…","type":"message","role":"assistant","model":"shannon-3","content":[],"usage":{"input_tokens":0,"output_tokens":0}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"thinking","thinking":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"thinking_delta","thinking":"Three sentences: what it is, how it is framed, why it is used."}}

event: ping
data: {"type": "ping"}

event: content_block_stop
data: {"type":"content_block_stop","index":1}

event: content_block_start
data: {"type":"content_block_start","index":2,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":2,"delta":{"type":"text_delta","text":"Server-sent events let a server push text over one HTTP reply."}}

event: content_block_stop
data: {"type":"content_block_stop","index":2}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":1190,"output_tokens":84}}

event: message_stop
data: {"type":"message_stop"}

Keep-alive

Dihantar oleh Penerangan
Keluarga Shannon 3, shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 Peristiwa ping dengan data {"type": "ping"}, setiap 15 saat.
Model open-weight yang dihoskan Baris komen : keepalive, setiap 15 saat semasa model bekerja.

Stream yang gagal

Kegagalan selepas stream bermula ialah peristiwa error dengan badan yang sama seperti balasan ralat: {"type": "error", "error": {"type", "message"}}. Peristiwa penutup, message_delta dan message_stop, masih mengikuti. Anggap balasan gagal dan hantar permintaan sekali lagi.

Ralat

Ralat menggunakan badan ralat Anthropic: type ialah error, dan objek error mengandungi type dan message. Jadual menyenaraikan apa yang paling kerap dipulangkan oleh endpoint ini. Senarai penuh, beserta apa yang perlu dicuba semula, mempunyai halaman tersendiri. Pengendalian Ralat

400 JSON
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}
Status Jenis Mesej Bila
401 authentication_error Missing authentication
Invalid API key
Tiada kunci API dihantar, atau kunci itu tidak dikenali atau telah dibatalkan.
400 invalid_request_error unknown model: <id> model bukan id model Shannon.
400 invalid_request_error No user message provided Peringkat Shannon: permintaan tidak mempunyai teks pengguna dan tiada tools.
400 invalid_request_error <id> does not accept image input Imej dihantar kepada model open-weight yang dihoskan tanpa input imej.
422 invalid_request_error Failed to deserialize the JSON body into the target type: … messages tiada, atau sesuatu medan mempunyai jenis JSON yang salah.
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan max_tokens lebih besar daripada baki anda yang tinggal.
429 rate_limit_error Too many requests. Retry in <n>s. Perlindungan lonjakan: lebih daripada 120 permintaan dalam satu minit pada akaun anda.
429 rate_limit_error Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan shannon-coder-1: panggilan Shannon Coder pelan anda untuk tetingkap 4 jam semasa telah habis digunakan.
500 server_error The model backend failed to answer. Please retry. Model tidak menghasilkan balasan. Hantar permintaan sekali lagi.
502 api_error The model backend failed to answer. Please retry. Model tidak menghasilkan balasan. Hantar permintaan sekali lagi.

Mengira token

POST /v1/messages/count_tokens menerima badan yang sama dengan permintaan mesej (model, system, messages, tools) dan memulangkan {"input_tokens": n}: bilangan token input yang akan dicaj untuk permintaan itu. Ia berfungsi untuk model open-weight yang dihoskan, percuma dan tidak dikira oleh perlindungan lonjakan.

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com",
)

count = client.messages.count_tokens(
    model="DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    system="You are a physics teacher. Answer in two sentences.",
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
)

print(count.input_tokens)

Pengiraan mempunyai halaman tersendiri, dengan endpoint teks biasa dan had-hadnya. Pengiraan token