Responses API

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

Kërkesa më e vogël është një id modeli dhe një tekst. Përgjigjja nuk bëhet me stream përveç nëse e kërkoni.

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

Përgjigjja është një objekt response. output i saj mban arsyetimin, kur modeli ka arsyetuar, dhe mesazhin:

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

Fushat e kërkesës

model dhe input janë ato që i duhen një kërkese. Kolona Zbatohet nga emërton modelet te të cilat një fushë ndryshon përgjigjen. Modelet open-weight të hostuara janë dymbëdhjetë id-të e listës së modeleve; familja Shannon 3 është shannon-3, shannon-3-pro, shannon-3.1 dhe shannon-3.1-pro. Modelet dhe çmimet

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user dhe prompt_cache_key pranohen që kodi ekzistues i klientit të punojë pa ndryshime. Ato nuk e ndryshojnë përgjigjen. Meqë nuk ruhet bisedë, një kërkesë vijuese i mban radhët e mëparshme te input.

Elementët e hyrjes

Një element hyrjeje është ose një mesazh, me role dhe content, ose një element i tipizuar që mban një thirrje mjeti ose rezultatin e saj. content është string ose varg pjesësh.

Vendosini udhëzimet në fushën instructions. Me një id të familjes Shannon 3, vendosini udhëzimet që duhet të mbahen në mesazhin user.

Elementët e output të një përgjigjeje mund të kthehen te input siç janë: elementët message dhe function_call lexohen, elementët reasoning kapërcehen.

Pjesët e përmbajtjes

Te nivelet Shannon imazhet dhe skedarët lexohen nga elementi i fundit user i input. Madhësitë dhe kufijtë kanë faqen e tyre. Imazhet dhe skedarët

Një kërkesë me udhëzime dhe opsione

Kjo kërkesë dërgon udhëzime, një bisedë si elementë hyrjeje, një kufi dalje, një temperaturë dhe një përpjekje arsyetimi. Përdor një model open-weight të hostuar, i cili i zbaton të gjitha.

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

Përgjigjja e një modeli open-weight të hostuar ka id, object, model, created_at, status, output dhe usage. usage i saj shton tokens-at e lexuar nga cache-i dhe tokens-at e shpenzuar për arsyetim:

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

Objekti i përgjigjes

id, object, status, output dhe usage janë në çdo përgjigje. Ndërtojeni kodin tuaj mbi to.

Elementët e daljes

SDK-të OpenAI e bashkojnë për ju tekstin e mesazhit te response.output_text.

Streaming

Vendosni stream në true për server-sent events. Çdo frame ka një rresht event: me emrin e ngjarjes dhe një rresht data: me një objekt JSON; objekti e përsërit emrin te type. Lidhini delta-t me elementin e tyre sipas output_index.

Me SDK-në OpenAI, lexojini ngjarjet sipas type:

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

Ngjarjet arrijnë në këtë radhë. Grupet për arsyetimin, mesazhin dhe thirrjet e mjeteve shfaqen vetëm kur përgjigjja i ka.

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

Një stream që dështon

Te nivelet Shannon një përgjigje e dështuar mbaron me response.failed në vend të response.completed. response.status i saj është failed dhe response.error mban një code, rate_limit_exceeded ose server_error, dhe një message.

Te modelet open-weight të hostuara një dështim është ngjarje error me code api_error dhe një message. response.completed vijon prapë pas saj.

Trajtojeni një stream si të dështuar kur përmban një ngjarje response.failed ose error, dhe dërgoni kërkesën përsëri.

Mjetet

Një mjet është një funksion që e ekzekuton kodi juaj. Përshkruajeni te tools; kur modeli e dëshiron, përgjigjja mban një element function_call në vend të mesazhit ose pranë tij.

Një përkufizim mjeti te tools:

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

output i një përgjigjeje që e thërret:

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

Ekzekutojeni funksionin, pastaj dërgojeni kërkesën përsëri me thirrjen dhe rezultatin e saj të shtuar te input:

[
  {
    "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\"}"
  }
]

Lexohen vetëm mjetet e llojit function. Te shannon-1.6-*, shannon-2-* dhe shannon-coder-1 skema parameters zvogëlohet në fjalët kyçe të zakonshme JSON Schema: oneOf lexohet si anyOf, dhe fjalë kyçe si $ref, additionalProperties, const, default dhe title nuk i kalohen modelit.

Vlerat required dhe një funksion i emërtuar të tool_choice zbatohen nga modelet open-weight të hostuara.

Cikli i mjeteve përshkruhet i plotë në faqen e vet. Thirrje funksionesh

Dalje e strukturuar

Ky format e shkruan daljen e strukturuar si text.format. Skema qëndron drejtpërdrejt te format, pranë name dhe strict, jo nën një anëtar json_schema si te Chat Completions.

• {"type": "json_object"} kërkon çdo objekt JSON.
• {"type": "json_schema", "name", "schema", "strict"} kërkon JSON që ndjek skemën tuaj. strict është true kur e lini jashtë.

{
  "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-i arrin si tekst te pjesa output_text e mesazhit; parsojeni vetë. Një model open-weight i hostuar pa dalje të strukturuar kthen 400.

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

Cili model e pranon cilën formë listohet në faqen e vet. Dalje të strukturuara

Arsyetimi

Një model që arsyeton e kthen arsyetimin si element dalje të llojit reasoning, para mesazhit. Në një stream arrin si ngjarje response.reasoning_summary_text.delta.

Modelet open-weight të hostuara zbatojnë reasoning.effort: off, low, medium ose high, me high kur nuk dërgoni asgjë. off nuk kthen element arsyetimi. Dërgojeni si objekt; një string i zhveshur nuk lexohet në këtë endpoint.

Përpjekjet përshkruhen në faqen e tyre. Përpjekja e arsyetimit

Kufiri i daljes

max_output_tokens është 4,096 kur nuk e dërgoni. Është numri i tokens-ave që rezervohet nga bilanci juaj kur kërkesa fillon; kur përgjigjja është e plotë, ajo sasi zëvendësohet me atë që përdori kërkesa. Një vlerë që nuk ngjit në bilancin tuaj të mbetur kthen 429 Quota exceeded.

Kufizon gjatësinë e përgjigjes te shannon-1.6-*, shannon-2-* dhe shannon-coder-1, dhe gjatësinë e tekstit të përgjigjes te modelet open-weight të hostuara.

Në këtë endpoint shannon-coder-1 faturohet në tokens nga bilanci juaj, si çdo model tjetër.

Trupi i një kërkese mund të jetë deri në 32 MiB. Kufijtë dhe bilanci

Gabimet

Gabimet përdorin trupin e gabimit të OpenAI: një objekt error me type dhe message; disa mbajnë edhe code dhe param me vlerën null. Tabela liston ato që ky endpoint kthen më shpesh. Lista e plotë, me atë që duhet provuar përsëri, ka faqen e vet. Trajtimi i gabimeve