أول طلب في Java باستخدام openai-java: عنوان URL الأساسي، المفتاح، الاستهلاك

لاستدعاء CheapTokens من Java، احتفظ بحزمة SDK الرسمية openai-java وغيّر ثلاثة أشياء: عنوان URL الأساسي (https://api.cheaptokens.dev/v1)، ومفتاح API، ومعرّف النموذج، الذي يُمرَّر كـ String عادي. يرسل البرنامج أدناه إكمال محادثة واحدًا ويطبع الإجابة وfinish_reason واستهلاك الرموز. يحتاج إلى Java 8 أو أحدث.

إذا كان فريقك يملك بالفعل خدمة Spring تتحدث إلى OpenAI، فهذا هو الترحيل بأكمله: لا عميل جديد، ولا أصناف طلب جديدة.

أضف التبعية#

يعرض README الخاص بحزمة SDK (github.com/openai/openai-java، تم التحقق منه في 4 نوفمبر 2026) الإصدار 4.99.0، والمجموعة com.openai، والقطعة openai-java. لا يطبع README تاريخ إصدار، لذا تحقق من المستودع للحصول على أحدث إصدار قبل نسخ هذا.

<dependency>
  <groupId>com.openai</groupId>
  <artifactId>openai-java</artifactId>
  <version>4.99.0</version>
</dependency>

implementation("com.openai:openai-java:4.99.0")

تعمل القطع المستقلة عن الأطر على Java 8+، لذا فإن JDK المؤسسي الأقدم ليس عائقًا.

عيّن المفتاح وعنوان URL الأساسي خارج الكود#

تقرأ حزمة SDK متغيرَي بيئة: OPENAI_API_KEY وOPENAI_BASE_URL. يلتقط OpenAIOkHttpClient.fromEnv() كليهما، لذا لا يصل المفتاح أبدًا إلى ملفات المصدر لديك. (تعمل أيضًا خصائص النظام openai.apiKey وopenai.baseUrl ولها الأولوية على المتغيرات.)

export OPENAI_API_KEY="your-cheaptokens-key"
export OPENAI_BASE_URL="https://api.cheaptokens.dev/v1"

عنوان URL الأساسي الافتراضي لحزمة SDK هو https://api.openai.com/v1. تجاهل السطر الثاني وسيذهب طلبك إلى هناك، بمفتاح CheapTokens لا يعرفه. هذه إحدى طرق الحصول على 401 عند التشغيل الأول. لمعرفة أين تحتفظ بالمفتاح وكيف تُبقيه خارج git، راجع تخزين مفتاح API بأمان.

البرنامج#

أنشئ FirstRequest.java:

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.chat.completions.ChatCompletion;
import com.openai.models.chat.completions.ChatCompletionCreateParams;

public class FirstRequest {
  public static void main(String[] args) {
    OpenAIClient client = OpenAIOkHttpClient.fromEnv();

    ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
        .model("deepseek-ai/DeepSeek-V4-Flash-0731")
        .addUserMessage("Explain in two sentences what a token is.")
        .maxCompletionTokens(300L)
        .build();

    ChatCompletion completion = client.chat().completions().create(params);
    ChatCompletion.Choice choice = completion.choices().get(0);

    System.out.println(choice.message().content().orElse("(no text)"));
    System.out.println("finish_reason: " + choice.finishReason());
    completion.usage().ifPresent(u ->
        System.out.println("input " + u.promptTokens()
            + ", output " + u.completionTokens()));
  }
}

تستحق بضعة أسطر نظرة ثانية.

• .model("deepseek-ai/DeepSeek-V4-Flash-0731"). تستخدم أمثلة README الخاصة بحزمة SDK ثوابت مُنمّطة مثل ChatModel.GPT_5_2، لكن المُنشئ يملك أيضًا تحميلًا زائدًا model(String)، لذا يعمل أي معرّف. استخدم المعرّف الكامل من وثائق CheapTokens: الاسم المختصر deepseek-v4-flash-0731 هو كيفية وسم الأسعار على الموقع؛ أما API فيريد المعرّف الكامل مع بادئة deepseek-ai/. لست متأكدًا من معرّف؟ اعرض النماذج باستخدام GET /v1/models.
• .maxCompletionTokens(300L). حدّ أعلى لطول الإجابة، كـ long. يسمح DeepSeek-V4-Flash بما يصل إلى 32,768 رمز إخراج لكل إجابة، لذا فإن 300 هنا خيار لإبقاء العرض التوضيحي قصيرًا، وليس حدًّا للنموذج.
• content() هو Optional. لهذا يملك البرنامج orElse. الرد المكوّن من استدعاءات أدوات فقط لا يحتوي على نص.
• usage() هو Optional أيضًا. يطبعه ifPresent عندما يرسله الخادم.

قم بتجميعه وتشغيله بالطريقة التي يفعلها بناؤك (mvn compile exec:java -Dexec.mainClass=FirstRequest، أو مهمة JavaExec في Gradle). يجب أن تحصل على شرح لرمز، ثم سطر finish_reason: … يحتوي على stop، ثم سطر يحتوي على عدد رموز الإدخال والإخراج. إذا قال finish_reason إن length، فقد بلغت الإجابة حدّ 300 رمز لديك وقُطعت: ارفع الرقم (لماذا يحدث ذلك).

يعيد usage() عدد رموز الموجّه والإكمال والإجمالي (promptTokens()، completionTokens()، totalTokens()).

عيّن القيم صراحةً باستخدام المُنشئ#

تحتاج الاختبارات، أو خدمة بعدة عملاء، أحيانًا إلى قيم صريحة. نفس العميل، مبنيًّا يدويًا:

OpenAIClient client = OpenAIOkHttpClient.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .baseUrl("https://api.cheaptokens.dev/v1")
    .build();

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

ثلاثة أخطاء ستواجهها أولًا#

من السهل تفويت متغير بيئة فارغ في IDE: قد لا يرث تكوين تشغيل بدأ من شريط الأدوات المتغيرات التي صدّرتها في الطرفية. إذا كان المفتاح "معيَّنًا" لكنك ما زلت تحصل على 401، فأضف المتغيرات إلى تكوين التشغيل. المزيد عن هذه الرموز: API 401 أو 404: المفتاح، عنوان URL الأساسي، معرّف النموذج.

تكلفة طلب واحد#

لأنك تطبع usage، يمكنك تسعير الطلب قبل توسيعه. لنفترض أن خدمتك ترسل نحو 200 رمز إدخال وتحصل على 300 في المقابل. بأسعار اليوم يكلّف ذلك الطلب $0.000033 على DeepSeek-V4-Flash. يُحتسب الإدخال والإخراج معًا، وإجمالًا هذا أرخص من OpenRouter. يكرر الجدول ذلك لـ 1,000 طلب عبر نماذجنا:

الآن أدخل حركة المرور الخاصة بك. اسحب المنزلقات إلى الأرقام من أول سطر usage طبعته:

لمزيد من المساحة لكل إجابة أو شكل مختلف من أعباء العمل، يمنحك DeepSeek-V4-Flash نافذة سياق 380K وسعرًا واحدًا في أي ساعة من اليوم؛ GLM-5.3-Flash (zai-org/GLM-5.3-Flash) بديل مباشر في نفس البرنامج: غيّر المعرّف، لا شيء آخر. الأسعار الحالية لجميع النماذج على صفحة الأسعار، وتُظهر الوثائق نفس الطلب بلغات أخرى. هل تفعل هذا في Go؟ راجع نسخة openai-go.