Developer guide
API გასაღებით ავთენტიფიკაცია
ჰედერი, რომელშიც API გასაღები უნდა ჩასვათ, და base URL, რომელიც SDK-ში უნდა დააყენოთ
CLEVI Gateway API-ის ერთი გასაღებით ახორციელებს ავთენტიფიკაციას OpenAI-თან თავსებად და Anthropic-თან თავსებად გზებზე.
კლიენტში დასაყენებელი მნიშვნელობებია გასაღების შემცველი ავთენტიფიკაციის ჰედერი და SDK-ის base URL. დაშვებული ჰედერის ფორმატი და base URL განსხვავდება სპეციფიკაციის მიხედვით.
პარამეტრების დასრულების შემდეგ მოდელების სიის მიღებით მაშინვე შეძლებთ ავთენტიფიკაციის შემოწმებას.
ავთენტიფიკაციის ჩავარდნის შემთხვევაში ბრუნდება 401, ხოლო ავთენტიფიკაციის გავლის შემდეგ, თუ ნებართვის ან ლიმიტის პირობები არ სრულდება, ბრუნდება 403.
API გასაღები მიიღეთ კონსოლის API გასაღების გვერდზე. იმავე გვერდზე შეგიძლიათ მართოთ გასაღების გაუქმება და გამოყენების ფარგლები.
ავთენტიფიკაციის ჰედერი
ორივე სპეციფიკაციაში API გასაღები თავსდება მოთხოვნის ერთ ჰედერში. გამოიყენება X-API-Key ან Authorization ჰედერი, ხოლო დაშვებული ფორმატი სპეციფიკაციის მიხედვით განსხვავდება.
| ჰედერი | OpenAI-თან თავსებადი | Anthropic-თან თავსებადი |
|---|---|---|
| X-API-Key: <გასაღები> | დაშვებულია | დაშვებულია |
| Authorization: Bearer <გასაღები> | დაშვებულია | დაშვებულია |
| Authorization: <გასაღები> (Bearer-ის გარეშე) | უარყოფილია | დაშვებულია |
OpenAI-თან თავსებად გზაზე Authorization ჰედერის გამოყენებისას საჭიროა Bearer პრეფიქსი. თუ გასაღებს მხოლოდ პრეფიქსის გარეშე გაგზავნით, Gateway მოთხოვნას უარყოფს.
ჰედერის სახელებში რეგისტრს მნიშვნელობა არ აქვს, ამიტომ Anthropic SDK-ის მიერ გაგზავნილი x-api-key ჰედერიც პირდაპირ მუშაობს. ორივე ჰედერის მითითების შემთხვევაში უპირატესობა ენიჭება X-API-Key-ის მნიშვნელობას.
base URL
ადრე გამოყენებული SDK-ის გამოყენება კვლავ შეგიძლიათ მხოლოდ base URL-ის ქვემოთ მოცემულ მისამართზე შეცვლით. ორი მისამართი განსხვავდება იმით, შეიცავს თუ არა /v1-ს, ამიტომ მიუთითეთ სპეციფიკაციის შესაბამისი მისამართი ზუსტად.
| სპეციფიკაცია | base URL | გზის წესი |
|---|---|---|
| OpenAI-თან თავსებადი | https://platform.clevi.net/api/v2/aiservice/openai/v1 | /v1 ჩართეთ base URL-ში. |
| Anthropic-თან თავსებადი | https://platform.clevi.net/api/v2/aiservice/anthropic | Anthropic SDK მოთხოვნის გზას თავად ამატებს /v1-ს, ამიტომ მისამართი მთავრდება /v1-მდე. |
ავთენტიფიკაციის შემოწმება
გასაღებისა და base URL-ის დაყენების შემდეგ, მოდელების სიის მოთხოვნით შეგიძლიათ შეამოწმოთ, გაიარეთ თუ არა ავტორიზაცია. ქვემოთ მოცემულ მაგალითებში ერთი და იგივე მოთხოვნა სრულდება curl-ის, OpenAI SDK-ისა და Anthropic SDK-ის გამოყენებით. sk-... ადგილას ჩასვით API გასაღებების ეკრანზე გაცემული გასაღები.
curl-ით მოთხოვნის შესრულებისას ორივე სპეციფიკაციისთვის მიუთითეთ სრული გზა, /v1/models-ის ჩათვლით. პირველი ბრძანება OpenAI-თან თავსებად გზაზე იყენებს X-API-Key ჰედერს, ხოლო მეორე ბრძანება Anthropic-თან თავსებად გზაზე — Authorization ჰედერს.
curl https://platform.clevi.net/api/v2/aiservice/openai/v1/models \
-H "X-API-Key: sk-..."
curl https://platform.clevi.net/api/v2/aiservice/anthropic/v1/models \
-H "Authorization: Bearer sk-..." \
-H "anthropic-version: 2023-06-01"OpenAI SDK-ში base_url-ისთვის მიუთითეთ მისამართი, რომელიც /v1-საც შეიცავს.
from openai import OpenAI
client = OpenAI(
api_key="sk-...",
base_url="https://platform.clevi.net/api/v2/aiservice/openai/v1",
)
for model in client.models.list():
print(model.id)Anthropic SDK-ში base_url-ისთვის მიუთითეთ მისამართი, რომელიც /v1-მდე მთავრდება.
ავტორიზაციისთვის უცვლელად გამოიყენეთ x-api-key ჰედერი, რომელსაც SDK აგზავნის.
from anthropic import Anthropic
client = Anthropic(
api_key="sk-...",
base_url="https://platform.clevi.net/api/v2/aiservice/anthropic",
)
for model in client.models.list(limit=20).data:
print(model.id)ნებისმიერი მაგალითის შემთხვევაში, თუ პასუხი 200-ია, ავტორიზაცია წარმატებით გაიარა, ხოლო პასუხის data-ში მოცემულია იმ მოდელების სია, რომელთა გამოძახება ამ გასაღებით შეგიძლიათ. თუ პასუხი 401-ია, მიზეზი შემდეგი განყოფილების თანმიმდევრობით შეამოწმეთ.
ავტორიზაციის შეცდომა
თუ გასაღები არ არსებობს, ვადაგასულია ან გაუქმებულია, ბრუნდება 401. OpenAI-თან თავსებად გზაზე გასაღების გარეშე მოთხოვნის შესრულებისას ბრუნდება ქვემოთ მოცემული სხეული, ხოლო Anthropic-თან თავსებად გზაზე error.type-ის მნიშვნელობაა authentication_error.
{
"error": {
"message": "API key is required.",
"type": "invalid_request_error"
}
}თუ მიიღეთ 401, შეამოწმეთ შემდეგი თანმიმდევრობით.
- API გასაღებების ეკრანზე შეამოწმეთ გასაღების სტატუსი. თუ გასაღები ვადაგასულია ან გაუქმებულია, შექმენით ახალი.
- შეამოწმეთ, ჰედერის სახელია თუ არა X-API-Key ან Authorization.
- თუ OpenAI-თან თავსებად გზაზე იყენებთ Authorization ჰედერს, შეამოწმეთ, აქვს თუ არა მას Bearer პრეფიქსი.
შესწორების შემდეგ ხელახლა შეასრულეთ მოდელების სიის მოთხოვნა ავტორიზაციის შემოწმების განყოფილებაში და დაადასტურეთ, რომ პასუხი 200-ია.
ერთად გამოსაყენებელი ჰედერები
ყველა შემდეგი ჰედერი არასავალდებულოა. პრობლემების თვალყურის დევნებისთვის გირჩევთ, მიუთითოთ X-Request-Id.
| ჰედერი | დანიშნულება | თუ გამოტოვებულია |
|---|---|---|
| X-Request-Id | მოთხოვნის თვალის დევნებისთვის საჭირო იდენტიფიკატორი. Anthropic-თან თავსებად მარშრუტში იგივე მნიშვნელობა პასუხის request-id ჰედერით ბრუნდება. | მას სერვერი გასცემს. |
| X-Region-Code | განსაზღვრავს გამოძახების რეგიონს. | მნიშვნელობაა global. |
| X-Product-Sku (ასევე შესაძლებელია მითითება query product_sku-ით) | პირდაპირ განსაზღვრავს ბილინგისთვის გამოსაყენებელ Product SKU-ს. ჰედერს query-ზე პრიორიტეტი აქვს და ძირითადად ხმოვან·voice მარშრუტებში გამოიყენება. | voice მარშრუტებში მისი გამოტოვება შეუძლებელია. audio/speech და audio/transcriptions Product-ს მოთხოვნის სხეულის model-ით ირჩევს. |
| anthropic-version / anthropic-beta | Anthropic-თან თავსებად მარშრუტში უცვლელად გადაეცემა. | ვერსიაა 2023-06-01. |
თუ 5xx შეცდომები მეორდება, შეგვატყობინეთ დახმარებისა და საკონტაქტო არხების მეშვეობით X-Request-Id-თან ერთად. თუ მნიშვნელობა თავად მიუთითეთ, მისი პირდაპირ შედარება შეგიძლიათ კლიენტის ჩანაწერებთან.