النص
إنشاء استجابة
ينشئ استجابة باستخدام تنسيق OpenAI Responses API
استخدم نقطة النهاية هذه عندما تتضمن accepted_request_formats الخاصة بالنموذج openai_responses. تستخدم الطلبات والاستجابات تنسيق Responses API ولا يتم تحويلها: فالنموذج الذي لا يدعم هذا التنسيق يُرجع 400 هنا، لذا استخدم Chat Completions معه. تعتمد الحقول الاختيارية والقيم المدعومة على النموذج المحدد.
جسم الطلب
معرّف النموذج المراد استخدامه. راجع النماذج للاطلاع على الخيارات المتاحة.
مدخلات الاستجابة. وهي اختيارية عندما يستخدم الطلب بدلاً من ذلك prompt قابلاً لإعادة الاستخدام أو يتابع استجابة مخزنة باستخدام previous_response_id.
كل عنصر هو كائن له type. الأنواع الشائعة هي:
message: رسالة محادثة تحتوي على دور ومحتوىfunction_call: طلب استدعاء دالةfunction_call_output: مخرجات استدعاء دالةreasoning: عنصر تفكير من استجابة سابقة. أعد إرساله دون تغيير
تعتمد أنواع العناصر الأخرى على النموذج المحدد.
بالنسبة للمدخلات متعددة الوسائط، يمكن أن يكون message.content إما نصاً عادياً أو مصفوفة من كتل المحتوى. بالنسبة للنماذج القادرة على معالجة الصور، مرّر الصور ككتل input_image بدلاً من تضمين عناوين URL أو سلاسل Base64 مباشرة في النص العادي.
أمثلة على كتل المحتوى:
{ "type": "input_text", "text": "Describe this image" }{ "type": "input_image", "image_url": "https://example.com/image.jpg" }{ "type": "input_image", "image_url": "data:image/png;base64,..." }
تعليمات النظام للنموذج (تعادل رسالة النظام).
الحد الأقصى لعدد الـ tokens المراد إنشاؤها.
درجة حرارة أخذ العينات. تعتمد القيم المدعومة والقيم الافتراضية على النموذج المحدد.
الأدوات التي قد يستدعيها النموذج. تعتمد الأنواع والتوليفات المدعومة على النموذج المحدد.
falseإذا كانت true، فسيتم إرجاع تدفق من الأحداث. راجع التدفق.
معرّف استجابة سابقة لمتابعة المحادثة منها. يجب أن تنتمي الاستجابة إلى حسابك وتكون لا تزال مخزنة؛ وإلا فسيُرجع الطلب 404 برمز response_not_found. تابع باستخدام النموذج الذي أنتجها. إذا كانت الخدمة التي أنتجت الاستجابة غير متاحة مؤقتاً، فقد يُرجع الطلب 503.
trueما إذا كان سيتم تخزين الاستجابة لاسترجاعها لاحقاً واستخدامها مع previous_response_id. عند تعيينها إلى false، لا تحتفظ TokenLab بالاستجابة، ولا يمكن لـ GET /v1/responses/{id} إرجاعها.
falseطلب التنفيذ غير المتزامن. يعتمد الدعم على النموذج المحدد. يُرجع استدعاء الإنشاء النتيجة على الفور، عادةً مع status بقيمة queued أو in_progress. استعلم دورياً من استرداد استجابة حتى تصبح status إما completed، أو incomplete، أو failed، أو cancelled. يمكن أن يُرجع الطلب في الخلفية 503 عندما تكون المعالجة في الخلفية غير متاحة مؤقتاً.
سياسة اختيار الأداة، مثل auto، أو none، أو required، أو كائن يحدد أداة واحدة. تعتمد القيم المدعومة على النموذج المحدد.
أقسام مخرجات إضافية لإرجاعها، عندما يدعمها النموذج المحدد.
خيارات التدفق. تتم إعادة توجيه include_obfuscation حيثما يدعم النموذج المحدد ذلك.
استراتيجية الاقتطاع للمحادثات الطويلة، عندما يدعمها النموذج المحدد.
تقدم TokenLab طلبات Responses وتفوترها وفقاً لمستوى الخدمة القياسي. يُقبل كل من auto وdefault. تتم إزالة القيم الأخرى، مثل flex أو priority، من الطلب، وتتم فوترة الطلب بالسعر القياسي.
مرجع لقالب prompt قابل لإعادة الاستخدام والمتغيرات.
بيانات وصفية مخصصة مخزنة مع الاستجابة.
إعدادات مخرجات النص. يعتمد دعم text.format على النموذج المحدد.
ما إذا كان يُسمح باستدعاءات أدوات متعددة بالتوازي، عندما يدعم النموذج المحدد ذلك.
معامل أخذ العينات النواتي (0-1).
خيارات الاستدلال، بما في ذلك effort، تعتمد على النموذج المحدد.
الاستجابة
معرّف فريد للاستجابة.
دائماً response.
طابع زمني بتنسيق Unix لوقت إنشاء الاستجابة.
حالة الاستجابة: queued، أو in_progress، أو completed، أو incomplete، أو failed، أو cancelled. تحقق من هذا الحقل حتى عندما ينجح طلب HTTP.
قائمة عناصر المخرجات التي أنشأها النموذج.
إحصائيات استخدام الـ tokens.
نقاط النهاية ذات الصلة
GET /v1/responses/{id}يسترد استجابة مخزنة.DELETE /v1/responses/{id}يحذف استجابة مخزنة. ولا يلغي عملية التوليد.POST /v1/responses/compactيضغط محادثة ويُرجع كائنresponse.compaction.wss://api.tokenlab.sh/v1/responsesينشئ استجابات عبر WebSocket. راجع التدفق.- نقاط النهاية Cancel وinput-items وinput-tokens غير متاحة حالياً.
الطلب
curl -X POST "https://api.tokenlab.sh/v1/responses" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-terra",
"input": [
{"type": "message", "role": "user", "content": "Hello!"}
],
"max_output_tokens": 1000
}'from openai import OpenAI
client = OpenAI(
api_key="sk-your-api-key",
base_url="https://api.tokenlab.sh/v1"
)
response = client.responses.create(
model="gpt-5.6-terra",
input=[
{"type": "message", "role": "user", "content": "Hello!"}
],
max_output_tokens=1000
)
print(response.output)import OpenAI from 'openai';
const client = new OpenAI({
apiKey: 'sk-your-api-key',
baseURL: 'https://api.tokenlab.sh/v1'
});
const response = await client.responses.create({
model: 'gpt-5.6-terra',
input: [
{ type: 'message', role: 'user', content: 'Hello!' }
],
max_output_tokens: 1000
});
console.log(response.output);package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
payload := map[string]interface{}{
"model": "gpt-5.6-terra",
"input": []map[string]interface{}{
{"type": "message", "role": "user", "content": "Hello!"},
},
"max_output_tokens": 1000,
}
body, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", "https://api.tokenlab.sh/v1/responses", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer sk-your-api-key")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["output"])
}<?php
$ch = curl_init('https://api.tokenlab.sh/v1/responses');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Authorization: Bearer sk-your-api-key'
],
CURLOPT_POSTFIELDS => json_encode([
'model' => 'gpt-5.6-terra',
'input' => [
['type' => 'message', 'role' => 'user', 'content' => 'Hello!']
],
'max_output_tokens' => 1000
])
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
print_r($data['output']);مثال على إدخال الرؤية (Vision)
استخدم النماذج القادرة على معالجة الصور عن طريق وضع الصور داخل message.content ككتل input_image. يمكن أن تكون قيمة image_url إما عنوان URL عاماً أو عنوان URL للبيانات بتنسيق Base64.
{
"model": "gpt-5.6-terra",
"input": [
{
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "Please describe this image."
},
{
"type": "input_image",
"image_url": "https://example.com/demo.jpg"
}
]
}
]
}{
"model": "gpt-5.6-terra",
"input": [
{
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "Please describe this image."
},
{
"type": "input_image",
"image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}
]
}
]
}الاستجابة
{
"id": "resp_abc123",
"object": "response",
"created_at": 1706000000,
"status": "completed",
"model": "gpt-5.6-terra",
"output": [
{
"id": "msg_abc123",
"type": "message",
"status": "completed",
"role": "assistant",
"content": [
{"type": "output_text", "text": "Hello! How can I help you today?", "annotations": []}
]
}
],
"usage": {
"input_tokens": 10,
"output_tokens": 12,
"total_tokens": 22
}
}الأخطاء
تستخدم الأخطاء كائن error بنمط OpenAI. الحالات الشائعة: 400 لحقل غير صالح أو لنموذج لا يدعم تنسيق Responses، و401 لمفتاح غير صالح، و402 لعدم كفاية الرصيد، و404 لـ previous_response_id غير معروف، و429 لتجاوز حد المعدل، و503 عندما يتعذر على النموذج تلبية الطلب حالياً. راجع التعامل مع أخطاء API.
التفويض
BearerAuth مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.
الموضع: header
الترويسات
سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.
القيم المتاحة
- "auto"
- "verified"
- "official"
مفتاح اختياري يوقف تشغيل ثانٍ لنفس الطلب. أرسل قيمة فريدة جديدة، مثل UUID، لكل طلب، واحتفظ بها لإعادة المحاولة بعد انتهاء المهلة. إعادة المحاولة بنفس المفتاح لا تعمل مرة أخرى: فهي تُرجع 409 مع idempotency_replay_unavailable، أو عادة idempotency_conflict عند تغيير النص الأساسي. استثناء: عندما تنتهي نتيجة غير متدفقة بعد قطع اتصال العميل، فإن إعادة المحاولة بنفس المفتاح والنص الأساسي في غضون 24 ساعة تُرجع تلك النتيجة (حتى 1 ميجابايت) مع الترويسة Idempotent-Replayed: true وبدون رسوم ثانية. يتم تجاهل المفتاح الذي يزيد طوله عن 255 حرفاً، ولا يتمتع الطلب حينها بحماية التكرار. مع background: true، تُرجع إعادة المحاولة بنفس المفتاح والنص الأساسي كائن الرد الأصلي بدلاً من ذلك ولا تنشئ أو تفرض رسوماً على رد ثانٍ؛ يتم رفض النص الأساسي المختلف، ولا يتم ضمان رمز الحالة الخاص به. راجع إعادة المحاولة بأمان باستخدام مفتاح التكرار.
1 <= length <= 255جسم الطلب
application/json
الاستجابة
application/json
application/json
application/json
application/json
application/json