מדריך API
Responses
POST /v1/responses בפורמט Responses של OpenAI. ה-endpoint לא שומר מצב, ולכן צריך לשלוח את כל השיחה בכל פעם.
ה-API של Responses של OpenAI, עם אותם מודלים, מפתחות וחיוב כמו השלמות הצ׳אט. הוא מתאים כשה-SDK או לולאת הסוכן שלך (Codex, ה-OpenAI Agents SDK) עובדים עם Responses ולא עם chat.
https://api.notholy.com/v1/responsesPOST https://api.notholy.com/v1/responsesבקשה
| שדה | סוג | חובה | הערות |
|---|---|---|---|
model | string | כן | מזהה מודל, למשל notholy-specter |
input | string או array | כן | פרומפט, או רשימת פריטים מסוג message, function_call או function_call_output. פריטים מסוגים אחרים מושמטים |
instructions | string | לא | פרומפט מערכת, ממוקם לפני input |
max_output_tokens | number | לא | מגבלת הפלט. ברירת המחדל היא המקסימום של המודל, והערך לא יכול לעבור אותו |
stream | boolean | לא | הערך true מחזיר אירועי response.* עם שם |
tools | array | לא | כלי פונקציה. סוגי כלים אחרים מושמטים |
tool_choice | string או object | לא | בשימוש כשהשדה tools מוגדר |
reasoning.effort | string | לא | אחד מערכי reasoning_efforts של המודל. כל ערך אחר מחזיר 400 |
temperature, top_p | number | לא | מועברים למודל |
ה-endpoint לא שומר מצב. השדה previous_response_id מחזיר 400 unsupported_parameter, והשדות store, metadata, text.format לא נלקחים בחשבון. יש לשלוח את כל השיחה בשדה input, כולל פריטים קודמים מסוג function_call או function_call_output.
תשובה בלי סטרימינג
{
"id": "resp_6mQ2x9",
"object": "response",
"created_at": 1793836800,
"status": "completed",
"model": "notholy-specter",
"output": [
{ "type": "reasoning", "id": "rs_1", "summary": [{ "type": "summary_text", "text": "…" }] },
{
"type": "message",
"id": "msg_1",
"status": "completed",
"role": "assistant",
"content": [{ "type": "output_text", "text": "AV:N means the attack works over the network…", "annotations": [] }]
}
],
"usage": {
"input_tokens": 18,
"input_tokens_details": { "cached_tokens": 0 },
"output_tokens": 96,
"output_tokens_details": { "reasoning_tokens": 40 },
"total_tokens": 114
},
"error": null,
"incomplete_details": null,
"store": false
}- כשמגבלת הפלט קוטעת את התשובה, הערך של
statusהואincomplete, עםincomplete_details.reason: "max_output_tokens". - קריאות לכלים חוזרות כפריטים מהצורה
{"type": "function_call", "call_id": "call_…", "name": "…", "arguments": "…"}. - כשהמודל הפעיל חשיבה, פריט
reasoningמופיע ראשון.
סטרימינג
עם "stream": true האירועים הם response.created, response.in_progress, ואז לכל פריט פלט: response.output_item.added, ה-deltas של הטקסט או של החשיבה, אירועי .done שלהם ואחריהם response.output_item.done. בסוף מגיע response.completed (או response.incomplete) עם usage. אין שורת [DONE]. כשל באמצע הזרם מגיע כאירוע response.failed.
דוגמה
curl https://api.notholy.com/v1/responses \
-H "Authorization: Bearer $NOTHOLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "notholy-specter", "input": "Summarize what CVSS 3.1 AV:N means."}'import os
from openai import OpenAI
client = OpenAI(base_url="https://api.notholy.com/v1", api_key=os.environ["NOTHOLY_API_KEY"])
r = client.responses.create(model="notholy-specter", input="Summarize what CVSS 3.1 AV:N means.")
print(r.output_text)import OpenAI from 'openai';
const client = new OpenAI({ baseURL: 'https://api.notholy.com/v1', apiKey: process.env.NOTHOLY_API_KEY });
const stream = await client.responses.create({ model: 'notholy-specter', input: 'Name two sources of EPSS data.', stream: true });
for await (const ev of stream) if (ev.type === 'response.output_text.delta') process.stdout.write(ev.delta);
console.log();שגיאות
אותם קודים כמו בהשלמות צ׳אט: 400 חסר model או input · 401 מפתח שגוי · 402 נגמרו הקרדיטים · 404 מודל לא מוכר · 429 עומס (יש לכבד את retry-after) · 503 המודל לא זמין. פרטים בשגיאות.