მიმოხილვა

API-ს რუკა: ყველა endpoint, როგორ გამოიყურება მოთხოვნა და შეცდომა, როგორ ფასდება გამოძახებები და რა უნდა იცოდეთ, როცა OpenAI-ს ან Anthropic-ის SDK-დან მოდიხართ.

Endpoints

ყველა endpoint ერთი base URL-ის ქვეშაა და HTTPS-ით მუშავდება.

Base URL

https://api.shannon-ai.com

Endpoint	ფორმატი	რისთვისაა
`POST /v1/chat/completions`	OpenAI Chat Completions	გააგზავნეთ საუბარი, მიიღეთ შემდეგი პასუხი. სტრიმინგით ან მის გარეშე.
`POST /v1/messages`	Anthropic Messages	იგივე, Anthropic SDK-ების მოთხოვნისა და პასუხის ფორმებით.
`POST /v1/responses`	OpenAI Responses	იგივე, Responses-ის ფორმებით. endpoint მდგომარეობას არ ინახავს: საუბარი ყოველ მოთხოვნასთან ერთად გააგზავნეთ.
`GET /v1/models`	OpenAI-ის მოდელების სია	მოდელების სია კონტექსტის ფანჯრით, ფასებითა და შესაძლებლობებით. გასაღები არ სჭირდება.
`POST /v1/tokenize`	Shannon API	დათვალეთ ტექსტის ან ჩატის მოთხოვნის ტოკენები hosted open-weight მოდელისთვის. უფასოა.
`POST /v1/messages/count_tokens`	Anthropic-ის ტოკენების დათვლა	დათვალეთ Messages მოთხოვნის შემავალი ტოკენები hosted open-weight მოდელისთვის. უფასოა.

სამი endpoint, რომლებიც ტექსტს აწარმოებენ, ერთსა და იმავე მოდელებს წვდებიან. აირჩიეთ ის, რომლის ფორმატსაც თქვენი კოდი უკვე იყენებს.

მოთხოვნის საფუძვლები

Header	აღწერა
`Authorization: Bearer <key>`	თქვენი API გასაღები. სავალდებულოა ყველა endpoint-ზე `GET /v1/models`-ის გარდა, თუ `x-api-key` არ გაგიგზავნიათ.
`x-api-key: <key>`	იგივე გასაღები header-ში, რომელსაც Anthropic SDK-ები აგზავნიან. იკითხება ყველა endpoint-ზე.
`Content-Type: application/json`	სავალდებულოა ყოველ `POST`-ზე. მის გარეშე პასუხია `415`.
`x-request-id: <your id>`	არასავალდებულო. თქვენი საკუთარი id მოთხოვნისთვის; ის პასუხის header-ში `x-request-id` ბრუნდება. მის გარეშე API თავად ქმნის 12 თექვსმეტობითი სიმბოლოსგან შემდგარს.

ყოველი POST-ის body ერთი JSON ობიექტია, 32 MiB-მდე.
ველი, რომელიც API-მ არ იცის, შეცდომას არ იწვევს და არაფერზე მოქმედებს. სხვა პროვაიდერისთვის დაწერილი მოთხოვნა ზედმეტი ველის გამო არ ვარდება.
ცნობილ ველს JSON-ის არასწორი ტიპით ან გამოტოვებულ სავალდებულო ველს პასუხობს 422. body, რომელიც ვალიდური JSON არ არის, 400-ით პასუხდება.
model არის ერთ-ერთი id გვერდიდან მოდელები და ფასები. დიდი და პატარა ასოები არ ითვლება.

პასუხი JSON-ია, ან server-sent events-ის სტრიმი, როცა მოთხოვნა stream-ს true-ზე აყენებს. ყოველი endpoint საკუთარ ფორმატში პასუხობს. ყოველ პასუხს აქვს header x-request-id.

რას გადის მოთხოვნა

მოთხოვნა მოდელის გაშვებამდე ფიქსირებული თანმიმდევრობით მოწმდება. პირველი შემოწმება, რომელიც ვარდება, პასუხობს, ამიტომ 401 body-ის შესახებ ჯერ არაფერს გეუბნებათ.

მოწმდება ამ თანმიმდევრობით	სტატუსი წარუმატებლობისას
API გასაღები	`401`
Body: ზომა, content type, JSON, ველების ტიპები	`413 · 415 · 400 · 422`
მოდელის id	`400`
Flood protection: 120 მოთხოვნა წუთში ანგარიშზე	`429`
ბალანსი: მოთხოვნის გამოტანის ბიუჯეტი უნდა ეტეოდეს	`429`

შეცდომის სტრუქტურა

შეცდომა არის JSON ობიექტი error-ით, რომელიც შეიცავს type-სა და message-ს. /v1/messages მას ისე ახვევს, როგორც Anthropic SDK-ები ელიან; ყველა სხვა გზა OpenAI-ს ფორმას იყენებს.

{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

წაიკითხეთ type და message. code და param მხოლოდ ზოგ შეცდომაზეა: ისინი არასავალდებულოდ მიიჩნიეთ. param ყოველთვის null-ია.
სტრიმის დაწყების შემდეგ სტატუსი უკვე 200-ია. წარუმატებლობა მაშინ შეცდომის ფრეიმის სახით მოდის სტრიმის შიგნით.
ყოველი შეცდომის პასუხი ატარებს header-ს x-request-id.

სტატუსი	ტიპი	როდის
`400`	`invalid_request_error`	სხეული არ არის ვალიდური JSON, მოდელის id უცნობია, ან მოდელი არ იღებს თქვენ მიერ გაგზავნილი სახის შემავალ მონაცემს.
`401`	`authentication_error`	გასაღები არ არის გადაცემული ან არავალიდურია.
`404`	`not_found_error`	ასეთი გზა არ არსებობს.
`405`	`api_error`	გზა არსებობს, მაგრამ მეთოდი არასწორია.
`413`	`invalid_request_error`	სხეული 32 MiB-ზე დიდია.
`415`	`invalid_request_error`	`Content-Type` არ არის `application/json`.
`422`	`invalid_request_error`	ველს აქვს არასწორი JSON ტიპი ან აუცილებელი ველი აკლია.
`429`	`rate_limit_error`	ბალანსი მოთხოვნას არ ფარავს, ერთ წუთში 120-ზე მეტი მოთხოვნა მოვიდა, ფანჯრის Shannon Coder-ის გამოძახებები ამოიწურა, ან მოდელი დატვირთულია. შეტყობინება მიუთითებს, რომელია მიზეზი.
`5xx`	`api_error`	სტატუსი `500`, `502`, `503` ან `504`: მოთხოვნა ვალიდური იყო, მაგრამ პასუხი ვერ მომზადდა. გაგზავნეთ ხელახლა. `500`-ს შეიძლება ჰქონდეს ტიპი `server_error`.

შეცდომების დამუშავება

ბილინგი და ბალანსი

ანგარიშზე ერთი ბალანსია და ჩატი და API მას ერთად იყენებენ: ჯერ დღევანდელი გეგმის ლიმიტს, შემდეგ შეძენილ კრედიტს. API-ს საკუთარი კვოტა არ აქვს.
მოთხოვნა ირეზერვებს თავის გამოტანის ბიუჯეტს (max_tokens, ნაგულისხმევი 4,096) და შემდეგ ირიცხება ტოკენებზე, რომლებიც რეალურად გამოიყენა, მოდელის ფასით.
ყოველი პასუხი თავის ტოკენების რაოდენობას usage-ში აჩვენებს. გვერდი Keys & usage აჩვენებს ბალანსს და იმას, რა დაჯდა თითოეული მოთხოვნა.
ყოველი მოთხოვნა თანაბრად მუშავდება. მოთხოვნების სიხშირის ერთადერთი ლიმიტია flood protection: 120 მოთხოვნა წუთში ანგარიშზე. პარალელურად გაგზავნილი მოთხოვნები რიგში დგანან.

ლიმიტები და ბალანსი მოდელები და ფასები გასაღებები და გამოყენება

ველები, რომლებიც მოდელზეა დამოკიდებული

ყველა მოდელი ერთსა და იმავე მოთხოვნას იღებს. რამდენიმე ველი მხოლოდ ზოგ მოდელზე მოქმედებს; ცხრილი ასახელებს, სად. endpoint-ების გვერდები ყველა ველს ჩამოთვლის.

ველი	აღწერა	მოქმედებს
`system`	ინსტრუქციები მოდელისთვის: `system` შეტყობინება Chat Completions-ზე, `system` Messages-ზე, `instructions` Responses-ზე.	Hosted open-weight მოდელები, `shannon-1.6-`, `shannon-2-`, `shannon-coder-1`
`temperature`	სემპლინგის ტემპერატურა.	Hosted open-weight მოდელები, `shannon-1.6-*`, `shannon-coder-1`
`top_p`	Nucleus სემპლინგი.	Hosted open-weight მოდელები
`seed`	სემპლინგის ფიქსირებული seed.	Hosted open-weight მოდელები
`stop`	მაქსიმუმ 4 stop sequence.	Hosted open-weight მოდელები
`reasoning_effort`	რამდენს მსჯელობს მოდელი პასუხამდე. `reasoning.effort` Responses-ზე, `thinking` Messages-ზე.	Hosted open-weight მოდელები
`web_search`	`true` მოდელს ამ მოთხოვნისთვის ვებში ძებნის საშუალებას აძლევს. ამ API-ს ველი, Chat Completions-სა და Messages-ზე.	Shannon-ის მოდელები `shannon-coder-1`-ის გარდა
`max_tokens`	გამოტანის ბიუჯეტი. ყველა მოდელზე ის თქვენი ბალანსიდან დარეზერვებულ რაოდენობას ადგენს.	პასუხის სიგრძის ლიმიტად: hosted open-weight მოდელები, `shannon-1.6-*`, `shannon-coder-1`

Chat Completions

თუ OpenAI SDK-დან მოდიხართ

დააყენეთ base URL https://api.shannon-ai.com/v1-ზე და გასაღები თქვენს Shannon გასაღებზე. Chat Completions და Responses გამოძახებები SDK-თან მაშინ ისე მუშაობს, როგორც არის.
model Shannon-ის id უნდა იყოს. სხვა პროვაიდერის მოდელის სახელს, მაგალითად gpt-4o, პასუხობს 400 და unknown model.
მსჯელობა საკუთარ ველში მოდის: reasoning_content content-ის გვერდით, შეტყობინებასა და სტრიმის delta-ებში.
სტრიმი თავის ბოლო chunk-ში ყოველთვის ატარებს usage-ს, finish_reason-თან ერთად.
ინსტრუმენტის გამოძახება სტრიმში ერთ chunk-ად მოდის სრული arguments სტრიქონით.
პასუხს ერთი choice აქვს.
OpenAI API-ს გზებს, რომლებიც ზემოთ ცხრილში არ არის, მაგალითად /v1/embeddings, 404-ით პასუხობენ.

Anthropic SDK-დან გადმოსვლა

დააყენეთ base URL https://api.shannon-ai.com-ზე, /v1-ის გარეშე, და გასაღები თქვენს Shannon გასაღებზე. SDK მას x-api-key-ის სახით აგზავნის.
model Shannon-ის id უნდა იყოს.
max_tokens ამ API-ზე არასავალდებულოა. მისი ნაგულისხმევი მნიშვნელობაა 4,096.
პასუხი შეიცავს კონტენტ-ბლოკებს ტიპებით thinking, text და tool_use. პირველი ბლოკი ყოველთვის ტექსტი არ არის: ბლოკები type-ით აირჩიეთ.
stop_reason არის end_turn ან tool_use. Shannon-ის მოდელის სტრიმი ასევე შეიძლება max_tokens-ით დასრულდეს.
anthropic-version და anthropic-beta მიიღება, ამიტომ SDK უცვლელად მუშაობს. მოთხოვნას ისინი არ სჭირდება.
/v1/messages-ზე შეცდომებს Anthropic-ის ფორმა აქვთ: {"type": "error", "error": {…}}.

კოდირების ინსტრუმენტები, რომლებიც ამ ფორმატებს იყენებენ, ერთნაირად დგება: base URL, გასაღები და Shannon-ის id როგორც მოდელი. CLI ინსტრუმენტები კოდირებისთვის