Оғози зуд

Аввалин дархостро фиристед: калидатонро гиред, як паём фиристед ва ҷавобро хонед. 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`		Id-и моделе, ки ҷавоб медиҳад. Id-ҳо дар Моделҳо ва нархҳо номбар шудаанд.
`messages`	`array`		Гуфтугӯ то ҳол: объектҳо бо `role` ва `content`. Паёми охирини `user` prompt аст. Ҳатмӣ.
`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`	Id-и нашршудаи моделе, ки ҷавоб дод, ҳатто вақте ки шумо тахаллус ё имлои дигар фиристодаед.
`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`	Reasoning-и модел пеш аз ҷавоб, ё `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 шумораи токенҳоро дорад, на пулро. Он чи даъват аз балансатон гирифт, барои ҳар дархост дар Калидҳо ва истифода нишон дода мешавад; чӣ тавр ҳисоб карда мешавад, дар Маҳдудиятҳо ва баланс аст. Маҳдудиятҳо ва баланс
Ҳар ҷавоб, хатогӣ ва ҷараён низ, сарлавҳаи x-request-id-ро дорад. Агар дархости шумо сарлавҳаи x-request-id-ро дошта бошад, қимати он бармегардад; дар ҳолати дигар қимат 12 аломати шонздаҳӣ аст. Онро дар ҷурнали худ нигоҳ доред: он ҳамин як дархостро ном мебарад.

Ҳамон даъват ҳамчун ҷараён

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
  }'

Ҳар фрейми ҷараён як хат аст, ки бо 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-и модел. Сифр ё бештар фрейм.	`{"reasoning_content": "…"}`	`null`
Ҷавоб, порча ба порча. Сифр ё бештар фрейм.	`{"content": "…"}`	`null`
Фрейми охирини JSON. Он ҳамчунин `usage`-ро дорад; шумо набояд онро дархост кунед.	`{}`	`"stop"`
Охири ҷараён: хати `data: [DONE]`.

Ҷавоб ҳолати 200 ва content-type: text/event-stream дорад. Ҳар фрейм хати data: <json> аст, ки хати холӣ пас аз он меояд.
Хати : ping ҳар 15 сония меояд. Он эзоҳест, ки пайвастшавиро кушода нигоҳ медорад; клиентҳои SSE онро мегузаронанд.
Нокомӣ пас аз кушода шудани ҷараён ҳамчун фрейми 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` id-и нашршуда нест. Id-ро аз Моделҳо ва нархҳо истифода баред.
`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`	Буҷаи баромади дархост ба балансатон ҷо намешавад.

Идораи хатогиҳо

Минбаъд ба куҷо равед

Моделҳо ва нархҳо — Модел интихоб кунед: id-ҳо, равзанаҳои контекст ва нархҳо.
Chat Completions — Ҳар майдони дархост, майдони ҷавоб ва рӯйдоди ҷараёни endpoint-е, ки даъват кардед.
Стриминг — Фреймҳои ҷараён, хатҳои keep-alive ва хатогиҳо дар дохили ҷараён.
Даъвати функсия — Бигузоред модел функсияҳои шуморо даъват кунад.
Маҳдудиятҳо ва баланс — Дархост чӣ захира мекунад ва чӣ арзиш дорад ва чанд дархост фиристода метавонед.
API Playground — Дархостҳоро дар браузер бо калиди худ санҷед.