وثائق GPT API

API متوافق مع OpenAI. غيّر الـ base_url والمفتاح فقط، وأي مكتبة أو أداة تدعم OpenAI تشتغل كما هي.

البدء السريع

احصل على مفتاح من مدير النظام، ثم جرّب:

curl __BASE__/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "__MODEL__",
    "messages": [{"role": "user", "content": "Say hello in one sentence"}]
  }'

from openai import OpenAI

client = OpenAI(base_url="__BASE__/v1", api_key="YOUR_API_KEY")

resp = client.chat.completions.create(
    model="__MODEL__",
    messages=[{"role": "user", "content": "Say hello in one sentence"}],
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "__BASE__/v1", apiKey: process.env.GPT_API_KEY });

const resp = await client.chat.completions.create({
  model: "__MODEL__",
  messages: [{ role: "user", content: "Say hello in one sentence" }],
});
console.log(resp.choices[0].message.content);

// pubspec.yaml: http: ^1.2.0
import 'dart:convert';
import 'package:http/http.dart' as http;

Future ask(String prompt) async {
  final res = await http.post(
    Uri.parse('__BASE__/v1/chat/completions'),
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: jsonEncode({
      'model': '__MODEL__',
      'messages': [{'role': 'user', 'content': prompt}],
    }),
  );
  if (res.statusCode == 429) throw Exception('Rate limit exceeded, retry shortly');
  if (res.statusCode != 200) throw Exception('HTTP error ${res.statusCode}');
  final data = jsonDecode(utf8.decode(res.bodyBytes));
  return data['choices'][0]['message']['content'];
}

$ch = curl_init('__BASE__/v1/chat/completions');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'model' => '__MODEL__',
        'messages' => [['role' => 'user', 'content' => 'Say hello in one sentence']],
    ]),
]);
$data = json_decode(curl_exec($ch), true);
echo $data['choices'][0]['message']['content'];

المصادقة

أرسل المفتاح في كل طلب داخل الهيدر:

Authorization: Bearer YOUR_API_KEY

الـ Endpoints

Tool/function calling والصور والـ embeddings لم يتم اختبارها بعد، فاختبرها في حالتك قبل الاعتماد عليها.

الموديلات

استخدم اسم الموديل في الحقل model:

Streaming

أضف "stream": true وستصلك الردود كأحداث SSE بصيغة OpenAI المعتادة، وتنتهي بـ data: [DONE].

curl -N __BASE__/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"__MODEL__","stream":true,"messages":[{"role":"user","content":"Count from 1 to 5"}]}'

stream = client.chat.completions.create(
    model="__MODEL__", stream=True,
    messages=[{"role": "user", "content": "Count from 1 to 5"}],
)
for chunk in stream:
    delta = chunk.choices[0].delta.content if chunk.choices else None
    if delta:
        print(delta, end="", flush=True)

const stream = await client.chat.completions.create({
  model: "__MODEL__", stream: true,
  messages: [{ role: "user", content: "Count from 1 to 5" }],
});
for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta?.content ?? "");

الحدود والأخطاء

لكل مفتاح حدود يحددها مدير النظام: عدد الطلبات في الدقيقة، والتوكنز في الدقيقة، والطلبات المتوازية. عند تجاوزها يرجع HTTP 429، وأيضاً عندما يستهلك الجميع حد الحساب الأساسي.

مثال لإعادة المحاولة عند 429:

import time
from openai import OpenAI, RateLimitError

def ask(prompt, retries=4):
    for i in range(retries):
        try:
            r = client.chat.completions.create(model="__MODEL__", messages=[{"role": "user", "content": prompt}])
            return r.choices[0].message.content
        except RateLimitError:
            time.sleep(2 ** i)          # 1s, 2s, 4s, 8s
    raise RuntimeError("Service busy, try again later")

ربط الأدوات

نصائح

• احتفظ بالمفتاح في متغير بيئة، ولا ترفعه إلى Git.
• اجعل max_tokens مناسباً لتوفير الحد.
• استخدم مفتاحاً مستقلاً لكل تطبيق أو بيئة (تطوير / إنتاج) ليسهل إيقافه وقياس استهلاكه.
• الخدمة تعتمد على حساب ChatGPT، وليست API رسمياً من OpenAI، فقد تتأثر بتغييرات من جهتهم. تعامل مع الأخطاء 5xx بإعادة المحاولة.