Saurin Farawa

Ku yi request na farko: ku sami maɓallinku, ku aika saƙo ɗaya ku karanta amsar. API yana magana da tsarin OpenAI da Anthropic, don haka SDK da kuke amfani da shi tuni yana aiki bayan kun canza base URL da maɓalli.

1. Ku sami maɓallinku

Kowane asusu yana da maɓallin API ɗaya. Ku shiga, ku buɗe Maɓallai & amfani ku kwafe shi. Maɓallin yana aiki a kowane endpoint da kowane model. Maɓallai & amfani

2. Nuna client ɗinku zuwa API

Dukkan endpoints suna ƙarƙashin base URL ɗaya. OpenAI SDK yana karɓarsa da /v1 a ƙarshe; Anthropic SDK yana karɓarsa ba tare da shi ba, domin yana ƙara /v1/messages da kansa.

Client	Base URL
OpenAI SDKs da clients masu jituwa da OpenAI	`https://api.shannon-ai.com/v1`
Anthropic SDKs	`https://api.shannon-ai.com`

Endpoints uku suna samar da rubutu. Suna isa ga models iri ɗaya; ku zaɓi wanda tsarinsa code ɗinku ke amfani da shi tuni.

Endpoint	Tsari
`POST /v1/chat/completions`	OpenAI Chat Completions
`POST /v1/messages`	Anthropic Messages
`POST /v1/responses`	OpenAI Responses

3. Ku aika request na farko

Ku aika saƙon user ɗaya zuwa shannon-3 a endpoint na Chat Completions. Ku maye gurbin YOUR_API_KEY da maɓallinku.

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

Field	Nau'i	Na asali	Bayani
`model`	`string`		Id na model da zai amsa. An lissafa ids a Models & farashi.
`messages`	`array`		Tattaunawar har yanzu: objects masu `role` da `content`. Saƙon `user` na ƙarshe shi ne prompt. Wajibi.
`max_tokens`	`integer`	`4096`	Output budget na request, daga 1 zuwa 65,536. Request yana ware wannan adadi daga balance ɗinku kuma ana cajin sa don abin da ya yi amfani da shi da gaske.
`stream`	`boolean`	`false`	`true` yana aika amsa guda-guda yayin da ake rubuta ta.

Jikin request JSON ne kuma yana buƙatar header Content-Type: application/json. Cikakken jerin fields yana a shafin endpoint. Chat Completions

Amsar

Kira ba tare da stream ba yana mayar da JSON object ɗaya idan amsar ta cika. Rubutu da lambobin da ke ƙasa misalai ne.

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

Field	Nau'i	Bayani
`id`	`string`	`chatcmpl-` da ke biye da haruffan hexadecimal 32.
`object`	`string`	Koyaushe `chat.completion`.
`created`	`integer`	Lokacin amsar a daƙiƙun Unix.
`model`	`string`	Id da aka wallafa na model da ya amsa, har ma idan kun aika alias ko wani rubutu.
`choices`	`array`	Koyaushe shigarwa ɗaya, mai `index` 0.
`choices[0].message.role`	`string`	Koyaushe `assistant`.
`choices[0].message.content`	`string \| null`	Amsar. Yana iya zama `null` idan amsar tana ɗauke da `tool_calls`.
`choices[0].message.reasoning_content`	`string \| null`	Reasoning na model kafin amsarsa, ko `null` idan babu.
`choices[0].message.tool_calls`	`array`	Yana nan ne kawai idan model ya kira ɗaya daga tools da kuka bayyana.
`choices[0].finish_reason`	`string`	`stop` ga amsa, `tool_calls` idan model ya kira tool.
`usage.prompt_tokens`	`integer`	Tokens da model ya karanta don wannan amsa. A `shannon-2-*` da iyalin Shannon 3 wannan na iya fin rubutun da kuka aika.
`usage.completion_tokens`	`integer`	Tokens da model ya rubuta.
`usage.total_tokens`	`integer`	Jimilla. Ana ƙididdige cajin model na Shannon daga wannan lamba.

usage yana ɗauke da ƙirgan tokens, ba kuɗi ba. Abin da kira ya ɗauka daga balance ɗinku ana nuna shi ga kowace request a Maɓallai & amfani; yadda ake ƙididdige shi yana a Iyakoki da balance. Iyakoki da balance
Kowace amsa, har da kuskure da stream, tana da header x-request-id. Idan request ɗinku yana ɗauke da header x-request-id, ƙimarsa tana dawowa; in ba haka ba ƙimar haruffan hexadecimal 12 ce. Ku ajiye ta a logs ɗinku: tana ambaton wannan request ɗaya.

Kira iri ɗaya a matsayin stream

Ku saita stream zuwa true don karanta amsar yayin da ake rubuta ta. Sauran komai a request yana nan yadda yake.

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

Kowane frame na stream layi ɗaya ne da ya fara da data: kuma yana ɗauke da JSON object. Frame ɗaya, an buga shi a layuka da yawa:

Frame ɗaya

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

Frames, bisa tsari	delta	finish_reason
Yayin da model ke yin reasoning. Frames sifili ko fiye.	`{"reasoning_content": "…"}`	`null`
Amsar, guda-guda. Frames sifili ko fiye.	`{"content": "…"}`	`null`
Frame na JSON na ƙarshe. Yana kuma ɗauke da `usage`; ba sai kun nema ba.	`{}`	`"stop"`
Ƙarshen stream: layin `data: [DONE]`.

Amsar tana da matsayi 200 da content-type: text/event-stream. Kowane frame layi ne data: <json> da ke biye da layi mara komai.
Layin : ping yana zuwa kowane daƙiƙa 15. Sharhi ne da ke riƙe haɗin a buɗe; SSE clients suna tsallake shi.
Gazawa bayan stream ya buɗe tana zuwa a matsayin frame data: {"error": {…}}. Matsayin yana nan 200, don haka ku duba frames.

Yawo

Idan kiran ya gaza

Kuskure JSON object ne mai error wanda ke ɗauke da type da message. Waɗannan su ne amsoshin da kira na farko ya fi haɗuwa da su.

Matsayi	Nau'i	Saƙo	Ma'anarsa
`401`	`authentication_error`	`Missing authentication`	Babu maɓalli da ya isa API. Ku aika `Authorization: Bearer` da ke biye da maɓallinku.
`401`	`authentication_error`	`Invalid API key`	Maɓallin ba shi ne maɓallin asusu na yanzu ba. Ku sake kwafar shi daga Maɓallai & amfani.
`400`	`invalid_request_error`	`unknown model: <id>`	`model` ba id da aka wallafa ba ne. Ku yi amfani da id daga Models & farashi.
`422`	`invalid_request_error`	`Failed to deserialize the JSON body into the target type…`	Field yana da nau'in JSON mara kyau, ko `messages` ya ɓace.
`429`	`rate_limit_error`	`Quota exceeded. Upgrade your plan at shannon-ai.com/plan`	Output budget na request bai shiga cikin balance ɗinku ba.

Kuskuren Gudanarwa

Inda za a je na gaba

Models & farashi — Zaɓi model: ids, context windows da farashi.
Chat Completions — Kowane field na request, field na amsa da stream event na endpoint da kuka kira.
Yawo — Frames na stream, layukan keep-alive da kurakurai a cikin stream.
Kiran Aiki — Ku bar model ya kira functions ɗinku.
Iyakoki da balance — Abin da request ke ware da kashewa, da requests nawa za ku iya aikawa.
Filin Wasan API — Ku gwada requests a browser da maɓallinku.