Responses API

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

Yêu cầu nhỏ nhất gồm một id model và một văn bản. Phản hồi không streaming trừ khi bạn yêu cầu.

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

Phản hồi là một đối tượng response. output của nó chứa phần suy luận, khi model có suy luận, và tin nhắn:

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

Các trường yêu cầu

model và input là những gì một yêu cầu cần. Cột Applied by nêu các model mà một trường làm thay đổi phản hồi. Các model open-weight hosted là mười hai id của danh sách model; dòng Shannon 3 là shannon-3, shannon-3-pro, shannon-3.1 và shannon-3.1-pro. Model và giá

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user và prompt_cache_key được chấp nhận để mã client hiện có chạy mà không cần thay đổi. Chúng không thay đổi phản hồi. Vì không có cuộc hội thoại nào được lưu, một yêu cầu tiếp theo mang các lượt trước trong input.

Các mục đầu vào

Một mục đầu vào là một tin nhắn, với role và content, hoặc một mục có kiểu mang một lần gọi tool hay kết quả của nó. content là một chuỗi hoặc một mảng các phần.

Hãy đặt chỉ dẫn vào trường instructions. Với id thuộc dòng Shannon 3, hãy đặt các chỉ dẫn bắt buộc phải giữ vào tin nhắn user.

Các mục trong output của một phản hồi có thể được đưa trở lại input nguyên trạng: các mục message và function_call được đọc, các mục reasoning bị bỏ qua.

Các phần nội dung

Trên các hạng Shannon, hình ảnh và tệp được đọc từ mục user cuối cùng của input. Kích thước và giới hạn có trang riêng. Hình ảnh và tệp

Yêu cầu có chỉ dẫn và tùy chọn

Yêu cầu này gửi chỉ dẫn, một cuộc hội thoại dưới dạng các mục đầu vào, giới hạn đầu ra, temperature và mức effort suy luận. Nó dùng một model open-weight hosted, model này áp dụng tất cả.

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

Phản hồi của model open-weight hosted có id, object, model, created_at, status, output và usage. usage của nó bổ sung các token đọc từ cache và các token dùng cho suy luận:

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

Đối tượng response

id, object, status, output và usage có trong mọi phản hồi. Hãy xây dựng mã của bạn dựa trên chúng.

Các mục đầu ra

Các SDK của OpenAI ghép văn bản của tin nhắn cho bạn trong response.output_text.

Streaming

Đặt stream là true để nhận server-sent events. Mỗi frame có một dòng event: với tên sự kiện và một dòng data: với đối tượng JSON; đối tượng lặp lại tên trong type. Hãy ghép các delta với mục của chúng theo output_index.

Với SDK của OpenAI, hãy đọc các sự kiện theo type của chúng:

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

Các sự kiện đến theo thứ tự này. Các nhóm cho suy luận, tin nhắn và lần gọi tool chỉ xuất hiện khi phản hồi có chúng.

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

Một stream thất bại

Trên các hạng Shannon, phản hồi thất bại kết thúc bằng response.failed thay cho response.completed. response.status của nó là failed và response.error chứa một code, là rate_limit_exceeded hoặc server_error, và một message.

Trên các model open-weight hosted, lỗi là một sự kiện error với code api_error và một message. response.completed vẫn theo sau nó.

Hãy coi stream là thất bại khi nó chứa sự kiện response.failed hoặc error, và gửi lại yêu cầu.

Công cụ

Tool là một hàm mà mã của bạn chạy. Hãy mô tả nó trong tools; khi model cần nó, phản hồi chứa một mục function_call thay cho, hoặc bên cạnh, tin nhắn.

Một định nghĩa tool trong tools:

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

output của một phản hồi gọi nó:

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

Hãy chạy hàm, rồi gửi lại yêu cầu với lần gọi và kết quả của nó được thêm vào 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\"}"
  }
]

Chỉ các tool loại function được đọc. Trên shannon-1.6-*, shannon-2-* và shannon-coder-1, schema parameters được rút gọn về các từ khóa JSON Schema phổ biến: oneOf được đọc như anyOf, và các từ khóa như $ref, additionalProperties, const, default và title không được chuyển cho model.

Các giá trị tool_choice là required và một hàm có tên được áp dụng bởi các model open-weight hosted.

Vòng lặp tool được mô tả đầy đủ ở trang riêng. Gọi hàm

Đầu ra có cấu trúc

Định dạng này viết đầu ra có cấu trúc là text.format. Schema nằm trực tiếp trong format, cạnh name và strict, không nằm dưới thành viên json_schema như trên Chat Completions.

• {"type": "json_object"} yêu cầu một đối tượng JSON bất kỳ.
• {"type": "json_schema", "name", "schema", "strict"} yêu cầu JSON theo schema của bạn. strict là true khi bạn bỏ qua nó.

{
  "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 đến dưới dạng văn bản trong phần output_text của tin nhắn; hãy tự phân tích nó. Model open-weight hosted không có đầu ra có cấu trúc trả về 400.

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

Model nào nhận dạng nào được liệt kê ở trang riêng. Đầu ra có cấu trúc

Suy luận

Model có suy luận trả về phần suy luận của nó dưới dạng một mục đầu ra loại reasoning, trước tin nhắn. Trong stream, nó đến dưới dạng các sự kiện response.reasoning_summary_text.delta.

Các model open-weight hosted áp dụng reasoning.effort: off, low, medium hoặc high, với high khi bạn không gửi gì. off không trả về mục suy luận. Hãy gửi nó dưới dạng đối tượng; chuỗi trần không được đọc trên endpoint này.

Các mức effort được mô tả ở trang riêng. Mức độ suy luận

Giới hạn đầu ra

max_output_tokens là 4,096 khi bạn không gửi nó. Đó là số token được dành riêng từ số dư của bạn khi yêu cầu bắt đầu; khi phản hồi hoàn tất, số lượng đó được thay bằng số yêu cầu đã dùng. Giá trị không vừa với số dư còn lại của bạn trả về 429 Quota exceeded.

Nó giới hạn độ dài phản hồi trên shannon-1.6-*, shannon-2-* và shannon-coder-1, và độ dài văn bản câu trả lời trên các model open-weight hosted.

Trên endpoint này, shannon-coder-1 được tính phí bằng token từ số dư của bạn, như mọi model khác.

Nội dung yêu cầu có thể lên tới 32 MiB. Giới hạn và số dư

Lỗi

Lỗi dùng nội dung lỗi của OpenAI: một đối tượng error với type và message; một số cũng mang code và param với giá trị null. Bảng liệt kê những gì endpoint này trả về thường xuyên nhất. Danh sách đầy đủ, kèm việc nên thử lại, có trang riêng. Xử lý lỗi