Responses API

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

Mafi ƙanƙantar request id ne na model da rubutu. Ba a yin streaming na amsar sai kun nema.

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

Amsar object ce na response. output ɗinta yana ɗauke da reasoning, idan model ya yi reasoning, da saƙon:

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

Fields na request

model da input ne abin da request ke buƙata. Ginshiƙin Wanda ke aiwatarwa yana sunayen models da field ke canza amsa a kansu. Hosted open-weight models su ne ids goma sha biyu na jerin models; iyalin Shannon 3 su ne shannon-3, shannon-3-pro, shannon-3.1 da shannon-3.1-pro. Models & farashi

Ana karɓar previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user da prompt_cache_key don code na client da ke akwai ya yi aiki ba tare da canji ba. Ba sa canza amsar. Domin ba a adana tattaunawa, request na gaba yana ɗauke da turns na baya a input.

Input items

Input item ko saƙo ne, mai role da content, ko item mai nau'i da ke ɗauke da kiran tool ko sakamakonsa. content string ne ko array na sassa.

Ku sa umarni a field na instructions. Da id na iyalin Shannon 3, ku saka umarnin da dole ya yi aiki a cikin saƙon user.

Ana iya mayar da items na output na amsa cikin input yadda suke: ana karanta items na message da function_call, ana tsallake items na reasoning.

Sassan abun ciki

A matakan Shannon ana karanta hotuna da fayiloli daga item na user na ƙarshe na input. Girma da iyakoki suna da shafinsu. Hotuna da fayiloli

Request mai instructions da zaɓuɓɓuka

Wannan request yana aika umarni, tattaunawa a matsayin items na input, iyakar output, temperature da effort na reasoning. Yana amfani da hosted open-weight model, wanda ke aiwatar da dukansu.

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

Amsar hosted open-weight model tana da id, object, model, created_at, status, output da usage. usage ɗinta yana ƙara tokens da aka karanta daga cache da tokens da aka kashe a kan reasoning:

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

Response object

id, object, status, output da usage suna cikin kowace amsa. Ku gina code ɗinku a kansu.

Items na output

OpenAI SDKs suna haɗa muku rubutun saƙon a cikin response.output_text.

Streaming

Ku saita stream zuwa true don server-sent events. Kowane frame yana da layin event: mai sunan event da layin data: mai object na JSON; object ɗin yana maimaita sunan a cikin type. Ku haɗa deltas da item ɗinsu ta output_index.

Da OpenAI SDK, ku karanta events ta type ɗinsu:

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

Events suna zuwa bisa wannan tsari. Rukunonin reasoning, saƙo da kiran tools suna bayyana ne kawai idan amsar tana da su.

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

Stream da ya gaza

A tiers na Shannon, amsar da ta gaza tana ƙarewa da response.failed maimakon response.completed. response.status ɗinta shi ne failed kuma response.error yana ɗauke da code, wato rate_limit_exceeded ko server_error, da message.

A hosted open-weight models, gazawa event ne na error mai code api_error da message. response.completed yana biyo bayansa duk da haka.

Ku ɗauki stream a matsayin wanda ya gaza idan yana ɗauke da event na response.failed ko error, sannan ku sake aika request ɗin.

Tools

Tool aiki ne da code ɗinku ke gudanarwa. Ku bayyana shi a cikin tools; idan model yana buƙatarsa, amsar tana ɗauke da item na function_call maimakon saƙon, ko kusa da shi.

Ma'anar tool a cikin tools:

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

output na amsar da ke kiran sa:

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

Ku gudanar da aikin, sannan ku sake aika request ɗin da kiran da sakamakonsa a ƙara cikin 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\"}"
  }
]

Ana karanta tools na nau'in function kawai. A shannon-1.6-*, shannon-2-* da shannon-coder-1 schema na parameters ana rage shi zuwa keywords na JSON Schema na gama gari: ana karanta oneOf a matsayin anyOf, kuma keywords kamar $ref, additionalProperties, const, default da title ba a mika su ga model ba.

Hosted open-weight models suna aiwatar da ƙimomin tool_choice required da aikin da aka ambaci suna.

An bayyana tool loop sosai a shafinsa na kansa. Kiran Aiki

Structured output

Wannan tsari yana rubuta structured output a matsayin text.format. Schema yana kai tsaye a cikin format, kusa da name da strict, ba a ƙarƙashin member na json_schema ba kamar a Chat Completions.

• {"type": "json_object"} yana neman kowane object na JSON.
• {"type": "json_schema", "name", "schema", "strict"} yana neman JSON da ke bin schema ɗinku. strict shi ne true idan kun bar shi.

{
  "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 yana zuwa a matsayin rubutu a ɓangaren output_text na saƙon; ku yi parse ɗinsa da kanku. Hosted open-weight model ba tare da structured output ba yana mayar da 400.

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

Wane model ke ɗaukar wane tsari an lissafa a shafinsa na kansa. Abubuwan da aka Tsara

Reasoning

Model da ke yin reasoning yana mayar da reasoning ɗinsa a matsayin item na output na nau'in reasoning, kafin saƙon. A cikin stream yana zuwa a matsayin events na response.reasoning_summary_text.delta.

Hosted open-weight models suna aiwatar da reasoning.effort: off, low, medium ko high, kuma high ne idan ba ku aika komai ba. off ba ya mayar da item na reasoning. Ku aika shi a matsayin object; ba a karanta string kaɗai a wannan endpoint ba.

An bayyana effort-effort a shafinsu na kansu. Reasoning effort

Iyakar output

max_output_tokens shi ne 4,096 idan ba ku aika shi ba. Shi ne adadin tokens da ake ware daga balance ɗinku lokacin da request ya fara; idan amsar ta cika, ana maye gurbin wannan adadi da abin da request ya yi amfani da shi. Ƙimar da ba ta shiga cikin balance ɗinku da ya rage tana mayar da 429 Quota exceeded.

Yana iyakance tsawon amsa a shannon-1.6-*, shannon-2-* da shannon-coder-1, da tsawon rubutun amsa a hosted open-weight models.

A wannan endpoint ana cajin shannon-coder-1 a tokens daga balance ɗinku, kamar kowane sauran model.

Jikin request na iya kaiwa 32 MiB. Iyakoki da balance

Kurakurai

Kurakurai suna amfani da jikin kuskure na OpenAI: object ɗin error mai type da message; wasu kuma suna ɗauke da code da param masu ƙimar null. Teburin yana lissafa abin da wannan endpoint ya fi mayarwa. Cikakken jerin, tare da abin da za a sake gwadawa, yana da shafinsa. Kuskuren Gudanarwa