أول طلب إلى CheapTokens في Python باستخدام requests، بدون SDK

لا تحتاج إلى حزمة openai للتحدث مع واجهة برمجة تطبيقات متوافقة مع OpenAI. يكفي استدعاء واحد بـ requests.post، ومفتاح Bearer، وجسم JSON، وسترى بالضبط ما يُرسل عبر الشبكة. يبني هذا الدليل ذلك السكربت لـ CheapTokens (https://api.cheaptokens.dev/v1/chat/completions) وينتهي بطباعة الإجابة وfinish_reason واستهلاك الرموز.

إنه خيار مناسب إذا كنت على جهاز مقيّد لا يحتوي إلا على requests، أو إذا كانت مهمة cron صغيرة لا ينبغي أن تجلب SDK، أو إذا أردت ببساطة فهم ما يفعله الـ SDK نيابةً عنك. يغطي دليل الطلب الأول مسارات الـ SDK وcurl وNode؛ وهذا هو مسار Python الصِرف.

السكربت كاملًا#

ضع مفتاحك في متغير بيئة أولًا (انظر كيفية تخزين مفتاح API بأمان)، ثم احفظ هذا باسم ask.py:

import os
import requests

url = "https://api.cheaptokens.dev/v1/chat/completions"
headers = {"Authorization": f"Bearer {os.environ['CHEAPTOKENS_API_KEY']}"}
payload = {
    "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
    "messages": [
        {"role": "user", "content": "Explain what a token is in two sentences."}
    ],
    "max_tokens": 200,
}

try:
    r = requests.post(url, headers=headers, json=payload, timeout=30)
    r.raise_for_status()
except requests.exceptions.Timeout:
    raise SystemExit("No reply within 30 seconds - try again or raise the timeout")
except requests.exceptions.HTTPError as e:
    raise SystemExit(f"HTTP {e.response.status_code}: {e.response.text}")

data = r.json()
choice = data["choices"][0]
print(choice["message"]["content"])
print("finish_reason:", choice["finish_reason"])
print("usage:", data["usage"])

شغّل python ask.py. معرّف النموذج هو معرّف البوابة الكامل، deepseek-ai/DeepSeek-V4-Flash-0731؛ وإذا لم تكن متأكدًا مما تضعه هناك، اعرض النماذج باستخدام GET /v1/models. لتجربة نموذج آخر، استبدل بـ zai-org/GLM-5.3-Flash ولا تغيّر شيئًا آخر: رصيد واحد يغطي جميع النماذج.

ماذا يفعل كل سطر#

إليك الأفكار الخمس التي يعتمد عليها السكربت. يشرح [Quickstart](requests) (وثائق حيّة، تم التحقق منها في 2 نوفمبر 2026) معظمها، ويحدد مرجع Chat Completions من OpenAI الحقول في الرد.

النقطة الثالثة هي التي يتجاهلها الناس. سكربت يتعلّق إلى الأبد في مهمة cron أسوأ بكثير من سكربت يفشل بصوت عالٍ بعد 30 ثانية.

اقرأ الرد#

الاستجابة الناجحة هي JSON. الأجزاء التي تهمك، وفقًا لمرجع Chat Completions:

• choices[0].message.content هو النص. يمكن أن يكون null، لذا لا تستدعِ دوال السلاسل النصية عليه دون تحقق.
• choices[0].finish_reason يوضح سبب توقف النموذج: stop (انتهى)، length (قطعه حد max_tokens)، tool_calls، content_filter.
• usage.prompt_tokens وusage.completion_tokens وusage.total_tokens هي ما تُحاسب عليه: الإدخال والإخراج ومجموعهما.

يكون للرد هذا الشكل (الأرقام عناصر نائبة):

{
  "choices": [
    {
      "message": {"role": "assistant", "content": "A token is a small piece of text..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 18, "completion_tokens": 52, "total_tokens": 70}
}

عندما لا يعمل#

يحوّل السكربت معظم حالات الفشل إلى سطر واحد من المخرجات. إليك ما يعنيه كل منها عادةً:

للاطلاع على أجسام الأخطاء الفعلية وفحص خطوة بخطوة للمفتاح وعنوان URL الأساسي ومعرّف النموذج، استخدم خطأ API 401 أو 404: مفتاح أو عنوان URL أساسي أو معرّف نموذج خاطئ. عقبتان أصغر: إذا رأيت KeyError: 'choices'، فقد حلّلت جسم خطأ كنجاح، ما يعني أن raise_for_status() تم تخطيه. وإذا كان جهازك يحتوي على ملف ~/.netrc، فقد يستخدم requests بيانات اعتماده بدلًا من ترويسة Authorization التي ضبطتها.

تكلفة استدعاء واحد#

بالأرقام النائبة من الرد أعلاه (حوالي 18 رمزًا إدخالًا و52 إخراجًا)، يكلّف استدعاء واحد لـ DeepSeek-V4-Flash $0.0000055. هذا رقم لا يمكنك استشعاره، لذا كبّره. لنفترض أن سكربتك يلخّص 1,000 تذكرة دعم يوميًا، بنحو 800 رمز إدخالًا و300 إخراجًا لكل واحدة:

الأسعار ثابتة لكل نموذج، دون ساعات ذروة، لذا يكلّف السكربت نفسه الشيء ذاته في الثالثة صباحًا وفي الظهيرة. الأسعار الحالية لكل نموذج على صفحة الأسعار، والوثائق تسرد نقاط النهاية.

إلى أين تذهب من هنا#

بمجرد أن يعمل هذا، تكون الخطوات التالية المعتادة حلقة على مدخلات كثيرة، أو إعادة المحاولة عند 429 (انظر 429 Too Many Requests: إعادة المحاولات مع التراجع)، أو الاستدعاء نفسه مع البث. وإذا كنت تفضّل ألا تدير HTTP بنفسك، فمسار الـ SDK يبعد تغييرًا واحدًا في base_url.