Responses API

POST https://api.shannon-ai.com/v1/responses

Ən kiçik sorğu model id-si və mətndir. İstəmədikcə cavab axınla verilmir.

from openai import OpenAI

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

response = client.responses.create(
    model="shannon-3",
    input="Say hello in one sentence.",
)

print(response.output_text)

import OpenAI from "openai";

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

const response = await client.responses.create({
  model: "shannon-3",
  input: "Say hello in one sentence.",
});

console.log(response.output_text);

curl https://api.shannon-ai.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-3",
    "input": "Say hello in one sentence."
  }'

Cavab response obyektidir. Onun output-u, model reasoning etdikdə reasoning-i və mesajı saxlayır:

{
  "id": "resp_5f0c1e7a9b3d4c62a8e1f07d2b46c9a3",
  "object": "response",
  "created_at": 1791625200,
  "model": "shannon-3",
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "metadata": {},
  "parallel_tool_calls": true,
  "temperature": null,
  "tool_choice": "auto",
  "tools": [],
  "top_p": null,
  "output": [
    {
      "id": "rs_8a2e6c1f4b7d4e03b9c5a1d70f3e2b64",
      "type": "reasoning",
      "summary": [
        {
          "type": "summary_text",
          "text": "The user wants a greeting in one sentence. Keep it short and friendly."
        }
      ]
    },
    {
      "id": "msg_1c7b9e3a5d2f4a86b0e4c8d19a6f7e25",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Hello, it is good to meet you.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 1184,
    "output_tokens": 46,
    "total_tokens": 1230
  }
}

Sorğu sahələri

Sorğuya model və input lazımdır. Applied by sütunu sahənin cavabı dəyişdirdiyi modelləri göstərir. Host edilən açıq çəkili modellər model siyahısındakı on iki id-dir; Shannon 3 ailəsi shannon-3, shannon-3-pro, shannon-3.1 və shannon-3.1-pro-dur. Modellər və qiymətlər

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user və prompt_cache_key mövcud klient kodunun dəyişmədən işləməsi üçün qəbul edilir. Onlar cavabı dəyişmir. Söhbət saxlanılmadığı üçün növbəti sorğu əvvəlki növbələri input-da daşıyır.

Giriş elementləri

Giriş elementi ya role və content olan mesajdır, ya da alət çağırışını və ya onun nəticəsini daşıyan tipli elementdir. content sətir və ya hissələr massividir.

Təlimatları instructions sahəsinə qoyun. Shannon 3 ailəsinin id-si ilə qüvvədə qalmalı təlimatları user mesajına qoyun.

Cavabın output elementləri olduğu kimi input-a qaytarıla bilər: message və function_call elementləri oxunur, reasoning elementləri keçilir.

Məzmun hissələri

Shannon pillələrində təsvirlər və fayllar input-un son user elementindən oxunur. Ölçülər və limitlər ayrıca səhifədədir. Təsvirlər və fayllar

Təlimatlar və seçimlərlə sorğu

Bu sorğu təlimatları, giriş elementləri kimi söhbəti, output limitini, temperature və reasoning effort göndərir. O, hamısını tətbiq edən host edilən açıq çəkili modeldən istifadə edir.

from openai import OpenAI

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

response = client.responses.create(
    model="DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    instructions="You are a physics teacher. Answer in two sentences.",
    input=[
        {"role": "user", "content": "Why is the sky blue?"},
        {"role": "assistant", "content": "Air scatters blue light more than red light."},
        {"role": "user", "content": "And why are sunsets red?"},
    ],
    max_output_tokens=512,
    temperature=0.3,
    reasoning={"effort": "low"},
)

for item in response.output:
    if item.type == "reasoning":
        print("reasoning:", item.summary[0].text)
    elif item.type == "message":
        print("answer:", item.content[0].text)
print(response.usage)

import OpenAI from "openai";

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

const response = await client.responses.create({
  model: "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
  instructions: "You are a physics teacher. Answer in two sentences.",
  input: [
    { role: "user", content: "Why is the sky blue?" },
    { role: "assistant", content: "Air scatters blue light more than red light." },
    { role: "user", content: "And why are sunsets red?" },
  ],
  max_output_tokens: 512,
  temperature: 0.3,
  reasoning: { effort: "low" },
});

for (const item of response.output) {
  if (item.type === "reasoning") console.log("reasoning:", item.summary[0].text);
  if (item.type === "message") console.log("answer:", item.content[0].text);
}
console.log(response.usage);

curl https://api.shannon-ai.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    "instructions": "You are a physics teacher. Answer in two sentences.",
    "input": [
      {"role": "user", "content": "Why is the sky blue?"},
      {"role": "assistant", "content": "Air scatters blue light more than red light."},
      {"role": "user", "content": "And why are sunsets red?"}
    ],
    "max_output_tokens": 512,
    "temperature": 0.3,
    "reasoning": {"effort": "low"}
  }'

Host edilən açıq çəkili modelin cavabında id, object, model, created_at, status, output və usage var. Onun usage-i keşdən oxunan tokenləri və reasoning-ə sərf olunan tokenləri əlavə edir:

{
  "usage": {
    "input_tokens": 58,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 67,
    "output_tokens_details": {
      "reasoning_tokens": 19
    },
    "total_tokens": 125
  }
}

Response obyekti

id, object, status, output və usage hər cavabda var. Kodunuzu bunların üzərində qurun.

Output elementləri

OpenAI SDK-ları mesajın mətnini sizin üçün response.output_text-də birləşdirir.

Streaming

Server-sent events üçün stream-i true təyin edin. Hər frame-də hadisənin adı olan event: sətri və JSON obyekti olan data: sətri var; obyekt adı type-da təkrarlayır. Delta-ları öz elementinə output_index ilə uyğunlaşdırın.

OpenAI SDK ilə hadisələri type-ına görə oxuyun:

from openai import OpenAI

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

stream = client.responses.create(
    model="shannon-3",
    input="Explain server-sent events in three sentences.",
    stream=True,
)

for event in stream:
    kind = getattr(event, "type", "error")     # an event without a type is an error event
    if kind == "response.reasoning_summary_text.delta":
        pass                                   # a piece of reasoning: event.delta
    elif kind == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif kind == "response.output_item.done" and event.item.type == "function_call":
        print("\ntool call:", event.item.name, event.item.arguments)
    elif kind == "response.completed":
        print("\n", event.response.usage)
    elif kind in ("response.failed", "error"):
        raise RuntimeError("the stream failed, send the request again")

import OpenAI from "openai";

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

const stream = await client.responses.create({
  model: "shannon-3",
  input: "Explain server-sent events in three sentences.",
  stream: true,
});

for await (const event of stream) {
  if (event.type === "response.reasoning_summary_text.delta") {
    // a piece of reasoning: event.delta
  } else if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  } else if (event.type === "response.output_item.done" && event.item.type === "function_call") {
    console.log("\ntool call:", event.item.name, event.item.arguments);
  } else if (event.type === "response.completed") {
    console.log("\n", event.response.usage);
  } else if (event.type === "response.failed" || event.type === "error") {
    throw new Error("the stream failed, send the request again");
  }
}

curl -N https://api.shannon-ai.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-3",
    "input": "Explain server-sent events in three sentences.",
    "stream": true
  }'

Hadisələr bu ardıcıllıqla gəlir. Reasoning, mesaj və alət çağırışları qrupları yalnız cavabda olduqda görünür.

event: response.created
data: {"type":"response.created","response":{"id":"resp_5f0c…","object":"response","status":"in_progress","output":[], …}}

event: response.in_progress
data: {"type":"response.in_progress","response":{"id":"resp_5f0c…","object":"response","status":"in_progress","output":[], …}}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_1c7b…","type":"message","role":"assistant","status":"in_progress","content":[]}}

event: response.content_part.added
data: {"type":"response.content_part.added","output_index":0,"content_index":0,"part":{"type":"output_text","text":""}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"Server-sent"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":" events let a server push text over one HTTP reply."}

event: response.output_text.done
data: {"type":"response.output_text.done","output_index":0,"content_index":0,"text":"Server-sent events let a server push text over one HTTP reply."}

event: response.content_part.done
data: {"type":"response.content_part.done","output_index":0,"content_index":0,"part":{"type":"output_text","text":"Server-sent events let a server push text over one HTTP reply."}}

event: response.output_item.done
data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_1c7b…","type":"message","role":"assistant","status":"completed","content":[{"type":"output_text","text":"Server-sent events let a server push text over one HTTP reply.","annotations":[]}]}}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_5f0c…","object":"response","status":"completed","output":[…],"usage":{"input_tokens":1190,"output_tokens":18,"total_tokens":1208}, …}}

Uğursuz olan axın

Shannon pillələrində uğursuz cavab response.completed əvəzinə response.failed ilə bitir. Onun response.status-u failed-dir və response.error code (rate_limit_exceeded və ya server_error) və message saxlayır.

Host edilən açıq çəkili modellərdə uğursuzluq code api_error və message olan error hadisəsidir. Ondan sonra yenə response.completed gəlir.

Axında response.failed və ya error hadisəsi varsa, onu uğursuz sayın və sorğunu yenidən göndərin.

Alətlər

Alət kodunuzun icra etdiyi funksiyadır. Onu tools-da təsvir edin; model onu istədikdə cavab mesajın əvəzinə və ya yanında function_call elementi saxlayır.

tools-da alət tərifi:

[
  {
    "type": "function",
    "name": "get_weather",
    "description": "Current weather for a city.",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string"
        }
      },
      "required": [
        "city"
      ]
    }
  }
]

Onu çağıran cavabın output-u:

[
  {
    "id": "call_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "type": "function_call",
    "name": "get_weather",
    "call_id": "call_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "arguments": "{\"city\":\"Paris\"}"
  }
]

Funksiyanı icra edin, sonra sorğunu çağırış və onun nəticəsi input-a əlavə edilərək yenidən göndərin:

[
  {
    "role": "user",
    "content": "What is the weather in Paris?"
  },
  {
    "type": "function_call",
    "call_id": "call_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "name": "get_weather",
    "arguments": "{\"city\":\"Paris\"}"
  },
  {
    "type": "function_call_output",
    "call_id": "call_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "output": "{\"temperature_c\": 18, \"sky\": \"cloudy\"}"
  }
]

Yalnız function tipli alətlər oxunur. shannon-1.6-*, shannon-2-* və shannon-coder-1-də parameters sxemi ümumi JSON Schema açar sözlərinə qədər azaldılır: oneOf anyOf kimi oxunur, $ref, additionalProperties, const, default və title kimi açar sözlər modelə ötürülmür.

tool_choice-un required və adlı funksiya dəyərlərini host edilən açıq çəkili modellər tətbiq edir.

Alət dövrəsi ayrıca səhifədə tam təsvir olunub. Funksiya çağırışı

Strukturlu çıxış

Bu format strukturlu çıxışı text.format kimi yazır. Sxem Chat Completions-dakı kimi json_schema üzvünün altında deyil, birbaşa format-da, name və strict-in yanında durur.

• {"type": "json_object"} istənilən JSON obyekti istəyir.
• {"type": "json_schema", "name", "schema", "strict"} sxeminizə uyğun JSON istəyir. Buraxdıqda strict true-dur.

{
  "model": "shannon-1.6-lite",
  "input": "Extract the city and the date: 'The conference opens in Lisbon on 12 May 2027.'",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "event",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "description": "ISO 8601 date"
          }
        },
        "required": [
          "city",
          "date"
        ]
      }
    }
  }
}

JSON mesajın output_text hissəsində mətn kimi gəlir; onu özünüz parse edin. Strukturlu çıxışı olmayan host edilən açıq çəkili model 400 qaytarır.

{"city": "Lisbon", "date": "2027-05-12"}

Hansı modelin hansı formanı qəbul etdiyi ayrıca səhifədə siyahıya alınıb. Strukturlaşdırılmış çıxışlar

Reasoning

Reasoning edən model reasoning-ini mesajdan əvvəl reasoning tipli output elementi kimi qaytarır. Axında o, response.reasoning_summary_text.delta hadisələri kimi gəlir.

Host edilən açıq çəkili modellər reasoning.effort-u tətbiq edir: off, low, medium və ya high, heç nə göndərmədikdə high. off reasoning elementi qaytarmır. Onu obyekt kimi göndərin; sadə sətir bu endpoint-də oxunmur.

Effort-lar ayrıca səhifədə təsvir olunub. Reasoning effort

Output limiti

max_output_tokens göndərmədiyiniz halda 4,096-dır. Bu, sorğu başlayanda balansınızdan ayrılan token sayıdır; cavab tamamlandıqda həmin miqdar sorğunun istifadə etdiyi ilə əvəz olunur. Qalan balansınıza sığmayan dəyər 429 Quota exceeded qaytarır.

O, shannon-1.6-*, shannon-2-* və shannon-coder-1-də cavabın uzunluğunu, host edilən açıq çəkili modellərdə isə cavab mətninin uzunluğunu məhdudlaşdırır.

Bu endpoint-də shannon-coder-1 hər digər model kimi balansınızdan tokenlərlə hesablanır.

Sorğu gövdəsi 32 MiB-a qədər ola bilər. Limitlər və balans

Xətalar

Xətalar OpenAI xəta gövdəsindən istifadə edir: type və message olan error obyekti; bəziləri həmçinin null dəyərli code və param daşıyır. Cədvəl bu endpoint-in ən çox qaytardıqlarını siyahıya alır. Nəyi yenidən cəhd etməli olduğunuzu göstərən tam siyahı ayrıca səhifədədir. Xəta idarəetməsi