احراز هویت

Authorization: Bearer YOUR_API_KEY

x-api-key: YOUR_API_KEY

هدرهای پذیرفته‌شده

هر دو هدر در هر endpoint از /v1 خوانده می‌شوند، با هر فرمتی که آن endpoint به آن صحبت می‌کند. یکی از آن‌ها را بفرستید.

با SDK OpenAI، کلید و base URL را تنظیم کنید؛ SDK مقدار Authorization: Bearer را می‌فرستد.

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": "Hello, Shannon!"}
    ]
)

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: 'Hello, Shannon!' }
  ]
});

console.log(response.choices[0].message.content);

curl -X POST "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": "Hello, Shannon!"}
    ]
  }'

با SDK Anthropic، کلید و base URL را بدون /v1 تنظیم کنید؛ SDK مقدار 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": "Hello, Shannon!"}
    ]
)

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

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.shannon-ai.com'
});

const message = await client.messages.create({
  model: 'shannon-3',
  max_tokens: 1024,
  messages: [
    { role: 'user', content: 'Hello, Shannon!' }
  ]
});

console.log(message.content.filter((block) => block.type === 'text').map((block) => block.text).join(''));

curl -X POST "https://api.shannon-ai.com/v1/messages" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-3",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, Shannon!"}
    ]
  }'

کدام endpointها کلید می‌خواهند

کلید شما

• کلید sk- است و پس از آن 43 نویسه از A–Z، a–z، 0–9، - و _: در مجموع 46 نویسه.
• هر حساب دقیقاً یک کلید دارد. اولین بار که «کلیدها و مصرف» را باز کنید ساخته می‌شود.
• کلید دسترسی کامل به API را برای حساب شما فراهم می‌کند: هر endpoint، هر مدل و کل موجودی.
• کلید تاریخ انقضا ندارد. تا وقتی آن را تعویض یا ابطال کنید کار می‌کند.

تعویض و ابطال

کلید را در صفحه «کلیدها و مصرف» تعویض و ابطال می‌کنید. کلیدها و مصرف

• هر دو بلافاصله اعمال می‌شوند: درخواست بعدی با کلید قدیمی با 401 پاسخ داده می‌شود. 60 ثانیه را حد بالای زمان لازم برای رد شدن کلید قدیمی در همه‌جا در نظر بگیرید.
• همه کلاینت‌های حساب از یک کلید استفاده می‌کنند، پس تعویض به همه آن‌ها می‌رسد. کلید جدید را بلافاصله پس از تعویض در کلاینت‌های خود بگذارید.
• موجودی، مصرف و محافظت در برابر هجوم درخواست متعلق به حساب هستند، نه به کلید. کلید جدید با همان موجودی و همان تعداد درخواست دقیقه جاری ادامه می‌دهد.

خطاها

هر خطای احراز هویت وضعیت 401 و نوع authentication_error دارد. پیام، حالت‌ها را از هم تفکیک می‌کند.

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "invalid_api_key",
    "param": null
  }
}

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

• در هر مسیری جز /v1/messages، شیء error همچنین code: "invalid_api_key" را دارد، حتی برای کلید گم‌شده، و param: null.
• کلید پیش از خواندن بدنه بررسی می‌شود. درخواست بدون کلید معتبر 401 می‌گیرد، حتی اگر بدنه‌اش نامعتبر یا بیش از حد بزرگ باشد.
• مقدار Authorization: Bearer که با sk- شروع نشود، کلید API در نظر گرفته نمی‌شود. 401 می‌گیرد با پیامی که می‌گوید توکن نامعتبر یا منقضی است.

مرورگرها و CORS

• API فقط برای فهرستی ثابت از originها به درخواست‌های مرورگر از مبدأ متفاوت (cross-origin) پاسخ می‌دهد. JavaScript روی صفحه‌ای از origin دیگر نمی‌تواند پاسخ‌های /v1 را بخواند.
• API را از سرور خود فراخوانی کنید و بگذارید صفحه‌تان با سرور شما صحبت کند. این کار کلید را هم از سورس صفحه دور نگه می‌دارد.
• کد سمت سرور و ابزارهای خط فرمان تحت تأثیر نیستند: این قاعده فقط توسط مرورگرها اعمال می‌شود.
• ورود به حساب در shannon-ai.com درخواست‌های /v1 را احراز هویت نمی‌کند. کوکی‌ها در آنجا خوانده نمی‌شوند؛ کلید تنها اعتبارنامه است.
• برای یک origin مجاز، مرورگر می‌تواند content-type، authorization، x-api-key، anthropic-version، anthropic-beta، openai-beta و x-request-id را بفرستد و هدر پاسخ x-request-id را بخواند.

امن نگه داشتن کلید

• کلید را روی سرور نگه دارید. آن را در صفحه‌های وب، برنامه‌های موبایل یا مخزن‌های عمومی نگذارید: هر کسی که آن را داشته باشد می‌تواند کل موجودی شما را خرج کند.
• کلید را از یک متغیر محیطی یا یک secret store بارگذاری کنید، نه اینکه آن را در کد بنویسید.
• اگر ممکن است کلید نشت کرده باشد، آن را در «کلیدها و مصرف» تعویض کنید. کلید قدیمی بلافاصله از کار می‌افتد.
• پس از نشت، فهرست درخواست‌ها را در «کلیدها و مصرف» بخوانید. همه درخواست‌هایی را که کلید در 30 روز گذشته ارسال کرده نشان می‌دهد.