النص

إنشاء استجابة

ينشئ استجابة باستخدام تنسيق OpenAI Responses API

POST
/v1/responses

استخدم نقطة النهاية هذه عندما تتضمن accepted_request_formats الخاصة بالنموذج openai_responses. تستخدم الطلبات والاستجابات تنسيق Responses API ولا يتم تحويلها: فالنموذج الذي لا يدعم هذا التنسيق يُرجع 400 هنا، لذا استخدم Chat Completions معه. تعتمد الحقول الاختيارية والقيم المدعومة على النموذج المحدد.

جسم الطلب

modelstringمطلوب

معرّف النموذج المراد استخدامه. راجع النماذج للاطلاع على الخيارات المتاحة.

inputstring | array

مدخلات الاستجابة. وهي اختيارية عندما يستخدم الطلب بدلاً من ذلك 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,..." }
instructionsstring

تعليمات النظام للنموذج (تعادل رسالة النظام).

max_output_tokensinteger

الحد الأقصى لعدد الـ tokens المراد إنشاؤها.

temperaturenumber

درجة حرارة أخذ العينات. تعتمد القيم المدعومة والقيم الافتراضية على النموذج المحدد.

toolsarray

الأدوات التي قد يستدعيها النموذج. تعتمد الأنواع والتوليفات المدعومة على النموذج المحدد.

streambooleanالافتراضي: false

إذا كانت true، فسيتم إرجاع تدفق من الأحداث. راجع التدفق.

previous_response_idstring

معرّف استجابة سابقة لمتابعة المحادثة منها. يجب أن تنتمي الاستجابة إلى حسابك وتكون لا تزال مخزنة؛ وإلا فسيُرجع الطلب 404 برمز response_not_found. تابع باستخدام النموذج الذي أنتجها. إذا كانت الخدمة التي أنتجت الاستجابة غير متاحة مؤقتاً، فقد يُرجع الطلب 503.

storebooleanالافتراضي: true

ما إذا كان سيتم تخزين الاستجابة لاسترجاعها لاحقاً واستخدامها مع previous_response_id. عند تعيينها إلى false، لا تحتفظ TokenLab بالاستجابة، ولا يمكن لـ GET /v1/responses/{id} إرجاعها.

backgroundbooleanالافتراضي: false

طلب التنفيذ غير المتزامن. يعتمد الدعم على النموذج المحدد. يُرجع استدعاء الإنشاء النتيجة على الفور، عادةً مع status بقيمة queued أو in_progress. استعلم دورياً من استرداد استجابة حتى تصبح status إما completed، أو incomplete، أو failed، أو cancelled. يمكن أن يُرجع الطلب في الخلفية 503 عندما تكون المعالجة في الخلفية غير متاحة مؤقتاً.

tool_choicestring | object

سياسة اختيار الأداة، مثل auto، أو none، أو required، أو كائن يحدد أداة واحدة. تعتمد القيم المدعومة على النموذج المحدد.

includearray

أقسام مخرجات إضافية لإرجاعها، عندما يدعمها النموذج المحدد.

stream_optionsobject

خيارات التدفق. تتم إعادة توجيه include_obfuscation حيثما يدعم النموذج المحدد ذلك.

truncationstring

استراتيجية الاقتطاع للمحادثات الطويلة، عندما يدعمها النموذج المحدد.

service_tierstring

تقدم TokenLab طلبات Responses وتفوترها وفقاً لمستوى الخدمة القياسي. يُقبل كل من auto وdefault. تتم إزالة القيم الأخرى، مثل flex أو priority، من الطلب، وتتم فوترة الطلب بالسعر القياسي.

promptobject

مرجع لقالب prompt قابل لإعادة الاستخدام والمتغيرات.

metadataobject

بيانات وصفية مخصصة مخزنة مع الاستجابة.

textobject

إعدادات مخرجات النص. يعتمد دعم text.format على النموذج المحدد.

parallel_tool_callsboolean

ما إذا كان يُسمح باستدعاءات أدوات متعددة بالتوازي، عندما يدعم النموذج المحدد ذلك.

top_pnumber

معامل أخذ العينات النواتي (0-1).

reasoningobject

خيارات الاستدلال، بما في ذلك effort، تعتمد على النموذج المحدد.

الاستجابة

idstring

معرّف فريد للاستجابة.

objectstring

دائماً response.

created_atinteger

طابع زمني بتنسيق Unix لوقت إنشاء الاستجابة.

statusstring

حالة الاستجابة: queued، أو in_progress، أو completed، أو incomplete، أو failed، أو cancelled. تحقق من هذا الحقل حتى عندما ينجح طلب HTTP.

outputarray

قائمة عناصر المخرجات التي أنشأها النموذج.

usageobject

إحصائيات استخدام الـ 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
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
  }'
Python
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)
JavaScript
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);
Go
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
<?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..."
        }
      ]
    }
  ]
}

الاستجابة

Response
{
  "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
AuthorizationBearer <token>

مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.

الموضع: header

الترويسات

X-TokenLab-Delivery-Policy?string

سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.

القيم المتاحة

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

مفتاح اختياري يوقف تشغيل ثانٍ لنفس الطلب. أرسل قيمة فريدة جديدة، مثل 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