Responses API

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

En küçük istek bir model kimliği ve bir metindir. Siz istemedikçe yanıt stream edilmez.

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

Yanıt bir response nesnesidir. output alanı, model akıl yürüttüyse akıl yürütmeyi ve mesajı içerir:

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

İstek alanları

Bir isteğin ihtiyaç duyduğu model ve input alanlarıdır. Uygulayan sütunu, bir alanın yanıtı değiştirdiği modelleri adlandırır. Host edilen açık ağırlıklı modeller, model listesindeki on iki kimliktir; Shannon 3 ailesi shannon-3, shannon-3-pro, shannon-3.1 ve shannon-3.1-pro modelleridir. Modeller ve fiyatlandırma

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user ve prompt_cache_key kabul edilir; böylece mevcut istemci kodu değişmeden çalışır. Yanıtı değiştirmezler. Hiçbir konuşma saklanmadığı için sonraki bir istek önceki turları input içinde taşır.

Giriş öğeleri

Bir giriş öğesi ya role ve content içeren bir mesaj ya da bir araç çağrısını veya sonucunu taşıyan türlü bir öğedir. content bir dize ya da parça dizisidir.

Talimatları instructions alanına koyun. Bir Shannon 3 ailesi kimliğiyle, geçerli olması gereken talimatları user mesajına koyun.

Bir yanıtın output öğeleri olduğu gibi input içine geri konabilir: message ve function_call öğeleri okunur, reasoning öğeleri atlanır.

İçerik parçaları

Shannon katmanlarında görseller ve dosyalar input içindeki son user öğesinden okunur. Boyutların ve sınırların kendi sayfası vardır. Görseller ve dosyalar

Talimatlar ve seçeneklerle bir istek

Bu istek talimatları, giriş öğeleri olarak bir konuşmayı, bir çıktı sınırını, bir sıcaklığı ve bir akıl yürütme effort'unu gönderir. Hepsini uygulayan, host edilen bir açık ağırlıklı model kullanır.

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 edilen bir açık ağırlıklı modelin yanıtında id, object, model, created_at, status, output ve usage bulunur. usage alanı önbellekten okunan token'ları ve akıl yürütmeye harcanan token'ları ekler:

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

Response nesnesi

id, object, status, output ve usage her yanıtta bulunur. Kodunuzu bunlar üzerine kurun.

Çıktı öğeleri

OpenAI SDK'ları mesajın metnini sizin için response.output_text içinde birleştirir.

Streaming

Server-sent events için stream değerini true yapın. Her frame'de olayın adını taşıyan bir event: satırı ve bir JSON nesnesi içeren bir data: satırı bulunur; nesne adı type içinde tekrarlar. Delta'ları öğelerine output_index ile eşleştirin.

OpenAI SDK'sı ile olayları type alanlarına göre okuyun:

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

Olaylar bu sırayla gelir. Akıl yürütme, mesaj ve araç çağrıları grupları yalnızca yanıtta varsa 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}, …}}

Başarısız olan bir stream

Shannon katmanlarında başarısız bir yanıt, response.completed yerine response.failed ile biter. response.status değeri failed olur ve response.error bir code (rate_limit_exceeded veya server_error) ile bir message içerir.

Host edilen açık ağırlıklı modellerde bir başarısızlık, code değeri api_error ve bir message içeren bir error olayıdır. Ardından yine response.completed gelir.

Bir stream'de response.failed ya da error olayı varsa stream'i başarısız sayın ve isteği yeniden gönderin.

Araçlar

Araç, kodunuzun çalıştırdığı bir fonksiyondur. Onu tools içinde tanımlayın; model onu istediğinde yanıt, mesajın yerine ya da yanında bir function_call öğesi içerir.

tools içinde bir araç tanımı:

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

Onu çağıran bir yanıtın output alanı:

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

Fonksiyonu çalıştırın, sonra çağrıyı ve sonucunu input içine ekleyerek isteği yeniden gönderin:

[
  {
    "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ızca function türündeki araçlar okunur. shannon-1.6-*, shannon-2-* ve shannon-coder-1 modellerinde parameters şeması ortak JSON Schema anahtar sözcüklerine indirgenir: oneOf, anyOf gibi okunur; $ref, additionalProperties, const, default ve title gibi anahtar sözcükler modele iletilmez.

tool_choice değerlerinden required ve adı verilen bir fonksiyon, host edilen açık ağırlıklı modeller tarafından uygulanır.

Araç döngüsü kendi sayfasında ayrıntılı olarak anlatılır. Fonksiyon Çağırma

Yapılandırılmış çıktı

Bu biçim yapılandırılmış çıktıyı text.format olarak yazar. Şema, Chat Completions'taki gibi bir json_schema üyesinin altında değil, doğrudan format içinde, name ve strict yanında yer alır.

• {"type": "json_object"} herhangi bir JSON nesnesi ister.
• {"type": "json_schema", "name", "schema", "strict"} şemanıza uyan JSON ister. strict, göndermezseniz true olur.

{
  "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 parçasında metin olarak gelir; kendiniz ayrıştırın. Yapılandırılmış çıktısı olmayan, host edilen bir açık ağırlıklı model 400 döndürür.

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

Hangi modelin hangi biçimi kabul ettiği kendi sayfasında listelenir. Yapılandırılmış Çıktılar

Akıl yürütme

Akıl yürüten bir model, akıl yürütmesini mesajdan önce reasoning türünde bir çıktı öğesi olarak döndürür. Bir stream'de response.reasoning_summary_text.delta olayları olarak gelir.

Host edilen açık ağırlıklı modeller reasoning.effort değerini uygular: off, low, medium veya high; hiçbir şey göndermezseniz high. off akıl yürütme öğesi döndürmez. Bir nesne olarak gönderin; çıplak bir dize bu uç noktada okunmaz.

Effort düzeyleri kendi sayfasında anlatılır. Akıl yürütme çabası

Çıktı sınırı

max_output_tokens, göndermediğinizde 4,096'dır. İstek başladığında bakiyenizden ayrılan token sayısıdır; yanıt tamamlandığında bu miktarın yerini isteğin kullandığı miktar alır. Kalan bakiyenize sığmayan bir değer 429 Quota exceeded döndürür.

shannon-1.6-*, shannon-2-* ve shannon-coder-1 modellerinde yanıtın uzunluğunu, host edilen açık ağırlıklı modellerde ise yanıt metninin uzunluğunu sınırlar.

Bu uç noktada shannon-coder-1, diğer tüm modeller gibi bakiyenizden token olarak ücretlendirilir.

Bir istek gövdesi en fazla 32 MiB olabilir. Limitler ve bakiye

Hatalar

Hatalar OpenAI hata gövdesini kullanır: type ve message içeren bir error nesnesi; bazıları ayrıca null değerli code ve param taşır. Tablo bu uç noktanın en sık döndürdüklerini listeler. Tam liste, nelerin yeniden deneneceğiyle birlikte, kendi sayfasındadır. Hata yönetimi