شروع سریع

اولین درخواست را بفرستید: کلید خود را بگیرید، یک پیام بفرستید و پاسخ را بخوانید. API با فرمت‌های OpenAI و Anthropic کار می‌کند، پس SDKای که از قبل استفاده می‌کنید پس از تغییر base URL و کلید کار می‌کند.

1. کلید خود را بگیرید

هر حساب یک کلید API دارد. وارد شوید، «کلیدها و مصرف» را باز کنید و آن را کپی کنید. کلید روی هر endpoint و هر مدل کار می‌کند. کلیدها و مصرف

2. کلاینت خود را به API وصل کنید

همه endpointها زیر یک base URL قرار دارند. SDK مربوط به OpenAI آن را با /v1 در پایان می‌گیرد؛ SDK مربوط به Anthropic آن را بدون آن می‌گیرد، چون /v1/messages را خودش اضافه می‌کند.

کلاینت	Base URL
SDKهای OpenAI و کلاینت‌های سازگار با OpenAI	`https://api.shannon-ai.com/v1`
SDKهای Anthropic	`https://api.shannon-ai.com`

سه endpoint متن تولید می‌کنند. به همان مدل‌ها می‌رسند؛ آن را انتخاب کنید که کد شما از قبل فرمتش را به کار می‌برد.

اندپوینت	فرمت
`POST /v1/chat/completions`	OpenAI Chat Completions
`POST /v1/messages`	Anthropic Messages
`POST /v1/responses`	OpenAI Responses

3. اولین درخواست را بفرستید

یک پیام user را به shannon-3 روی endpoint مربوط به Chat Completions بفرستید. YOUR_API_KEY را با کلید خود جایگزین کنید.

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

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

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

package main

import (
    "context"
    "fmt"
    openai "github.com/sashabaranov/go-openai"
)

func main() {
    config := openai.DefaultConfig("YOUR_API_KEY")
    config.BaseURL = "https://api.shannon-ai.com/v1"
    client := openai.NewClientWithConfig(config)

    resp, err := client.CreateChatCompletion(
        context.Background(),
        openai.ChatCompletionRequest{
            Model: "shannon-3",
            Messages: []openai.ChatCompletionMessage{
                {Role: "user", Content: "Hello, Shannon!"},
            },
            MaxTokens: 1024,
        },
    )
    if err != nil {
        panic(err)
    }
    fmt.Println(resp.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!"}
    ],
    "max_tokens": 1024
  }'

فیلد	نوع	پیش‌فرض	توضیحات
`model`	`string`		شناسه مدلی که پاسخ می‌دهد. شناسه‌ها در «مدل‌ها و قیمت‌ها» فهرست شده‌اند.
`messages`	`array`		گفتگو تا اینجا: اشیایی با `role` و `content`. آخرین پیام `user` پرامپت است. الزامی.
`max_tokens`	`integer`	`4096`	بودجه خروجی درخواست، از 1 تا 65,536. درخواست این مقدار را از موجودی شما رزرو می‌کند و برای آنچه واقعاً مصرف کرده محاسبه می‌شود.
`stream`	`boolean`	`false`	`true` پاسخ را در حین نوشته شدن تکه‌تکه می‌فرستد.

بدنه درخواست JSON است و هدر Content-Type: application/json لازم دارد. فهرست کامل فیلدها در صفحه endpoint است. Chat Completions

پاسخ

فراخوانی بدون stream وقتی پاسخ کامل شود یک شیء JSON برمی‌گرداند. متن‌ها و اعداد زیر نمونه هستند.

200 JSON

{
  "id": "chatcmpl-9b2f6c1e4a7d4f0f8a3c5d2e1b6a7c90",
  "object": "chat.completion",
  "created": 1791590400,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! What would you like to work on?",
        "reasoning_content": "A greeting. A short, friendly reply fits."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1386,
    "completion_tokens": 74,
    "total_tokens": 1460
  }
}

فیلد	نوع	توضیحات
`id`	`string`	`chatcmpl-` و پس از آن 32 نویسه هگزادسیمال.
`object`	`string`	همیشه `chat.completion`.
`created`	`integer`	زمان پاسخ بر حسب ثانیه Unix.
`model`	`string`	شناسه منتشرشده مدلی که پاسخ داد، حتی وقتی یک نام مستعار یا املای دیگر فرستاده باشید.
`choices`	`array`	همیشه یک مورد، با `index` برابر 0.
`choices[0].message.role`	`string`	همیشه `assistant`.
`choices[0].message.content`	`string \| null`	پاسخ. وقتی پاسخ `tool_calls` دارد می‌تواند `null` باشد.
`choices[0].message.reasoning_content`	`string \| null`	استدلال مدل پیش از پاسخش، یا وقتی وجود ندارد `null`.
`choices[0].message.tool_calls`	`array`	فقط وقتی وجود دارد که مدل یکی از ابزارهایی را که اعلام کرده‌اید فراخوانی کند.
`choices[0].finish_reason`	`string`	`stop` برای یک پاسخ، `tool_calls` وقتی مدل ابزاری فراخوانی می‌کند.
`usage.prompt_tokens`	`integer`	توکن‌هایی که مدل برای این پاسخ خواند. روی `shannon-2-*` و خانواده Shannon 3 این می‌تواند بیشتر از متنی باشد که فرستادید.
`usage.completion_tokens`	`integer`	توکن‌هایی که مدل نوشت.
`usage.total_tokens`	`integer`	مجموع. هزینه مدل Shannon از این عدد محاسبه می‌شود.

usage تعداد توکن‌ها را دارد، نه پول را. آنچه فراخوانی از موجودی شما برداشته به تفکیک هر درخواست در «کلیدها و مصرف» نشان داده می‌شود؛ نحوه محاسبه آن در «محدودیت‌ها و موجودی» آمده است. محدودیت‌ها و موجودی
هر پاسخ، حتی خطا و stream، هدر x-request-id دارد. اگر درخواست شما هدر x-request-id داشته باشد، مقدارش برمی‌گردد؛ در غیر این صورت مقدار 12 نویسه هگزادسیمال است. آن را در لاگ‌های خود نگه دارید: همین یک درخواست را مشخص می‌کند.

همان فراخوانی به‌صورت stream

stream را روی true بگذارید تا پاسخ را در حین نوشته شدن بخوانید. هر چیز دیگر در درخواست همان می‌ماند.

from openai import OpenAI

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

stream = client.chat.completions.create(
    model="shannon-3",
    messages=[
        {"role": "user", "content": "Hello, Shannon!"}
    ],
    max_tokens=1024,
    stream=True
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

import OpenAI from 'openai';

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

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

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}

curl -N -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!"}
    ],
    "max_tokens": 1024,
    "stream": true
  }'

هر فریم stream یک خط است که با data: شروع می‌شود و یک شیء JSON دارد. یک فریم، چاپ‌شده در چند خط:

یک فریم

{
  "id": "chatcmpl-9b2f6c1e4a7d4f0f8a3c5d2e1b6a7c90",
  "object": "chat.completion.chunk",
  "created": 1791590400,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "Hello! "
      },
      "finish_reason": null
    }
  ]
}

فریم‌ها، به ترتیب	delta	finish_reason
تا وقتی مدل استدلال می‌کند. صفر یا چند فریم.	`{"reasoning_content": "…"}`	`null`
پاسخ، تکه‌تکه. صفر یا چند فریم.	`{"content": "…"}`	`null`
آخرین فریم JSON. `usage` را هم دارد؛ لازم نیست آن را درخواست کنید.	`{}`	`"stop"`
پایان stream: خط `data: [DONE]`.

پاسخ وضعیت 200 و content-type: text/event-stream دارد. هر فریم یک خط data: <json> است که پس از آن یک خط خالی می‌آید.
خط : ping هر 15 ثانیه می‌رسد. این یک خط توضیح است که اتصال را باز نگه می‌دارد؛ کلاینت‌های SSE آن را رد می‌کنند.
شکست پس از باز شدن stream به‌صورت فریم data: {"error": {…}} می‌رسد. وضعیت 200 می‌ماند، پس فریم‌ها را بررسی کنید.

استریم

اگر فراخوانی ناموفق بود

خطا یک شیء JSON است که errorای دارد با type و message. این‌ها پاسخ‌هایی هستند که اولین فراخوانی بیشتر با آن‌ها روبه‌رو می‌شود.

وضعیت	نوع	پیام	معنا
`401`	`authentication_error`	`Missing authentication`	هیچ کلیدی به API نرسید. `Authorization: Bearer` را همراه کلید خود بفرستید.
`401`	`authentication_error`	`Invalid API key`	کلید، کلید فعلی هیچ حسابی نیست. آن را دوباره از «کلیدها و مصرف» کپی کنید.
`400`	`invalid_request_error`	`unknown model: <id>`	`model` شناسه منتشرشده نیست. از شناسه‌ای از «مدل‌ها و قیمت‌ها» استفاده کنید.
`422`	`invalid_request_error`	`Failed to deserialize the JSON body into the target type…`	نوع JSON یک فیلد نادرست است، یا `messages` وجود ندارد.
`429`	`rate_limit_error`	`Quota exceeded. Upgrade your plan at shannon-ai.com/plan`	بودجه خروجی درخواست در موجودی شما جا نمی‌شود.

مدیریت خطا

بعد کجا بروید

مدل‌ها و قیمت‌ها — یک مدل انتخاب کنید: شناسه‌ها، پنجره‌های زمینه و قیمت‌ها.
Chat Completions — هر فیلد درخواست، فیلد پاسخ و رویداد stream در endpointی که فراخوانی کردید.
استریم — فریم‌های stream، خطوط keep-alive و خطاها داخل stream.
فراخوانی توابع — بگذارید مدل توابع شما را فراخوانی کند.
محدودیت‌ها و موجودی — یک درخواست چه چیزی رزرو می‌کند و چقدر هزینه دارد، و چند درخواست می‌توانید بفرستید.
پلی‌گراند API — درخواست‌ها را با کلید خود در مرورگر امتحان کنید.