Responses API

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

Το μικρότερο αίτημα είναι ένα id μοντέλου και ένα κείμενο. Η απάντηση δεν έρχεται με streaming εκτός αν το ζητήσετε.

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

Η απάντηση είναι ένα αντικείμενο απάντησης. Το output της περιέχει τον συλλογισμό, όταν το μοντέλο συλλογίστηκε, και το μήνυμα:

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

Πεδία αιτήματος

Τα model και input είναι ό,τι χρειάζεται ένα αίτημα. Η στήλη Εφαρμόζεται από ονομάζει τα μοντέλα στα οποία ένα πεδίο αλλάζει την απάντηση. Τα φιλοξενούμενα μοντέλα ανοιχτών βαρών είναι τα δώδεκα ids της λίστας μοντέλων· η οικογένεια Shannon 3 είναι τα shannon-3, shannon-3-pro, shannon-3.1 και shannon-3.1-pro. Μοντέλα & τιμές

Τα previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user και prompt_cache_key γίνονται δεκτά ώστε ο υπάρχων κώδικας client να τρέχει αμετάβλητος. Δεν αλλάζουν την απάντηση. Επειδή δεν αποθηκεύεται συνομιλία, ένα αίτημα συνέχειας φέρει τους προηγούμενους γύρους στο input.

Στοιχεία εισόδου

Ένα στοιχείο εισόδου είναι είτε μήνυμα, με role και content, είτε στοιχείο με τύπο που φέρει μια κλήση εργαλείου ή το αποτέλεσμά της. Το content είναι string ή πίνακας από μέρη.

Βάλτε τις οδηγίες στο πεδίο instructions. Με id της οικογένειας Shannon 3, βάλτε τις οδηγίες που πρέπει να ισχύουν στο μήνυμα user.

Τα στοιχεία του output μιας απάντησης μπορούν να επιστρέψουν στο input ως έχουν: τα στοιχεία message και function_call διαβάζονται, τα στοιχεία reasoning παραλείπονται.

Μέρη περιεχομένου

Στα επίπεδα Shannon οι εικόνες και τα αρχεία διαβάζονται από το τελευταίο στοιχείο user του input. Τα μεγέθη και τα όρια έχουν τη δική τους σελίδα. Εικόνες και αρχεία

Ένα αίτημα με οδηγίες και επιλογές

Αυτό το αίτημα στέλνει οδηγίες, μια συνομιλία ως στοιχεία εισόδου, ένα όριο εξόδου, μια θερμοκρασία και μια προσπάθεια συλλογισμού. Χρησιμοποιεί φιλοξενούμενο μοντέλο ανοιχτών βαρών, το οποίο τα εφαρμόζει όλα.

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

Η απάντηση ενός φιλοξενούμενου μοντέλου ανοιχτών βαρών έχει id, object, model, created_at, status, output και usage. Το usage της προσθέτει τα tokens που διαβάστηκαν από το cache και τα tokens που δαπανήθηκαν στον συλλογισμό:

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

Το αντικείμενο απάντησης

Τα id, object, status, output και usage υπάρχουν σε κάθε απάντηση. Χτίστε τον κώδικά σας πάνω σε αυτά.

Στοιχεία εξόδου

Τα SDK της OpenAI ενώνουν για εσάς το κείμενο του μηνύματος στο response.output_text.

Streaming

Ορίστε το stream σε true για server-sent events. Κάθε frame έχει μια γραμμή event: με το όνομα του συμβάντος και μια γραμμή data: με ένα αντικείμενο JSON· το αντικείμενο επαναλαμβάνει το όνομα στο type. Αντιστοιχίστε τα deltas στο στοιχείο τους με το output_index.

Με το SDK της OpenAI, διαβάστε τα συμβάντα με βάση το 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
  }'

Τα συμβάντα φτάνουν με αυτή τη σειρά. Οι ομάδες για τον συλλογισμό, το μήνυμα και τις κλήσεις εργαλείων εμφανίζονται μόνο όταν η απάντηση τις έχει.

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 που αποτυγχάνει

Στα επίπεδα Shannon μια αποτυχημένη απάντηση τελειώνει με response.failed αντί για response.completed. Το response.status της είναι failed και το response.error περιέχει ένα code, rate_limit_exceeded ή server_error, και ένα message.

Στα φιλοξενούμενα μοντέλα ανοιχτών βαρών μια αποτυχία είναι συμβάν error με code api_error και ένα message. Το response.completed ακολουθεί παρ' όλα αυτά.

Θεωρήστε ένα stream αποτυχημένο όταν περιέχει συμβάν response.failed ή error, και στείλτε ξανά το αίτημα.

Εργαλεία

Ένα εργαλείο είναι μια συνάρτηση που εκτελεί ο κώδικάς σας. Περιγράψτε το στο tools· όταν το μοντέλο το θέλει, η απάντηση περιέχει ένα στοιχείο function_call αντί για το μήνυμα ή δίπλα σε αυτό.

Ένας ορισμός εργαλείου στο tools:

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

Το output μιας απάντησης που την καλεί:

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

Εκτελέστε τη συνάρτηση και μετά στείλτε ξανά το αίτημα με την κλήση και το αποτέλεσμά της προστιθέμενα στο 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\"}"
  }
]

Διαβάζονται μόνο εργαλεία τύπου function. Στα shannon-1.6-*, shannon-2-* και shannon-coder-1 το schema parameters περιορίζεται στις κοινές λέξεις-κλειδιά του JSON Schema: το oneOf διαβάζεται ως anyOf, και λέξεις-κλειδιά όπως τα $ref, additionalProperties, const, default και title δεν περνούν στο μοντέλο.

Οι τιμές required και συνάρτηση με όνομα του tool_choice εφαρμόζονται από τα φιλοξενούμενα μοντέλα ανοιχτών βαρών.

Ο βρόχος εργαλείων περιγράφεται πλήρως στη δική του σελίδα. Κλήση συναρτήσεων

Δομημένη έξοδος

Αυτή η μορφή γράφει τη δομημένη έξοδο ως text.format. Το schema βρίσκεται απευθείας στο format, δίπλα στα name και strict, όχι κάτω από ένα μέλος json_schema όπως στα Chat Completions.

• Το {"type": "json_object"} ζητά οποιοδήποτε αντικείμενο JSON.
• Το {"type": "json_schema", "name", "schema", "strict"} ζητά JSON που ακολουθεί το schema σας. Το strict είναι true όταν το παραλείψετε.

{
  "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 φτάνει ως κείμενο στο μέρος output_text του μηνύματος· κάντε parse μόνοι σας. Ένα φιλοξενούμενο μοντέλο ανοιχτών βαρών χωρίς δομημένη έξοδο επιστρέφει 400.

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

Ποιο μοντέλο δέχεται ποια μορφή αναγράφεται στη δική του σελίδα. Δομημένες έξοδοι

Συλλογισμός

Ένα μοντέλο που συλλογίζεται επιστρέφει τον συλλογισμό του ως στοιχείο εξόδου τύπου reasoning, πριν από το μήνυμα. Σε ένα stream φτάνει ως συμβάντα response.reasoning_summary_text.delta.

Τα φιλοξενούμενα μοντέλα ανοιχτών βαρών εφαρμόζουν το reasoning.effort: off, low, medium ή high, με high όταν δεν στέλνετε τίποτα. Το off δεν επιστρέφει στοιχείο reasoning. Στείλτε το ως αντικείμενο· ένα απλό string δεν διαβάζεται σε αυτό το endpoint.

Οι προσπάθειες περιγράφονται στη δική τους σελίδα. Προσπάθεια συλλογισμού

Όριο εξόδου

Το max_output_tokens είναι 4,096 όταν δεν το στέλνετε. Είναι ο αριθμός tokens που δεσμεύεται από το υπόλοιπό σας όταν ξεκινά το αίτημα· όταν η απάντηση ολοκληρωθεί, αυτό το ποσό αντικαθίσταται από όσα χρησιμοποίησε το αίτημα. Μια τιμή που δεν χωράει στο υπόλοιπό σας επιστρέφει 429 Quota exceeded.

Περιορίζει το μήκος της απάντησης στα shannon-1.6-*, shannon-2-* και shannon-coder-1, και το μήκος του κειμένου της απάντησης στα φιλοξενούμενα μοντέλα ανοιχτών βαρών.

Σε αυτό το endpoint το shannon-coder-1 χρεώνεται σε tokens από το υπόλοιπό σας, όπως κάθε άλλο μοντέλο.

Το σώμα ενός αιτήματος μπορεί να φτάσει τα 32 MiB. Όρια και υπόλοιπο

Σφάλματα

Τα σφάλματα χρησιμοποιούν το σώμα σφάλματος της OpenAI: ένα αντικείμενο error με type και message· ορισμένα φέρουν και τα code και param με τιμή null. Ο πίνακας απαριθμεί όσα επιστρέφει πιο συχνά αυτό το endpoint. Η πλήρης λίστα, με το τι να ξαναδοκιμάσετε, έχει τη δική της σελίδα. Χειρισμός σφαλμάτων