Java

استخدم مكتبة openai-java الرسمية مع api14. اضبط baseUrl في builder العميل ومرّر معرّفات النماذج (مثل openai/gpt-5-mini) كسلاسل نصية عادية.

التثبيت

Gradle:

implementation("com.openai:openai-java:4.+")

Maven:

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

ثم اضبط API14_API_KEY=sk-api14-... في بيئتك.

الإعداد

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;

OpenAIClient client = OpenAIOkHttpClient.builder()
    .baseUrl("https://api14.com/api/v1")
    .apiKey(System.getenv("API14_API_KEY"))
    .build();

يقرأ OpenAIOkHttpClient.fromEnv() المتغيرين OPENAI_BASE_URL وOPENAI_API_KEY بدلًا من ذلك، فيمكنك تبديل البيئات دون تغيير الكود:

export OPENAI_BASE_URL="https://api14.com/api/v1"
export OPENAI_API_KEY="sk-api14-..."

المحادثة

import com.openai.models.chat.completions.ChatCompletion;
import com.openai.models.chat.completions.ChatCompletionCreateParams;

ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
    .model("openai/gpt-5-mini")
    .addUserMessage("Explain vector databases in two sentences.")
    .build();

ChatCompletion completion = client.chat().completions().create(params);
completion.choices().get(0).message().content().ifPresent(System.out::println);

البث

import com.openai.core.http.StreamResponse;
import com.openai.models.chat.completions.ChatCompletionChunk;

ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
    .model("anthropic/claude-sonnet-4.5")
    .addUserMessage("Write a haiku about APIs.")
    .build();

try (StreamResponse<ChatCompletionChunk> stream = client.chat().completions().createStreaming(params)) {
    stream.stream()
        .flatMap(chunk -> chunk.choices().stream())
        .flatMap(choice -> choice.delta().content().stream())
        .forEach(System.out::print);
}

راجع البث.

استدعاء الأدوات

صِف الأداة بوصفها class، فيشتق SDK مخطط JSON Schema الخاص بها ويحلل المعاملات إلى كائن منها:

import com.fasterxml.jackson.annotation.JsonClassDescription;
import com.openai.models.chat.completions.*;
import java.util.Collection;

@JsonClassDescription("Current weather for a city")
static class GetWeather {
    public String city;
}

ChatCompletionCreateParams.Builder builder = ChatCompletionCreateParams.builder()
    .model("openai/gpt-5-mini")
    .addTool(GetWeather.class)
    .addUserMessage("What's the weather in Istanbul?");

while (true) {
    ChatCompletionMessage message = client.chat().completions().create(builder.build())
        .choices().get(0).message();
    builder.addMessage(message);
    if (message.toolCalls().map(Collection::isEmpty).orElse(true)) {
        message.content().ifPresent(System.out::println);
        break;
    }
    for (ChatCompletionMessageToolCall call : message.toolCalls().get()) {
        GetWeather args = call.asFunction().function().arguments(GetWeather.class);
        builder.addMessage(ChatCompletionToolMessageParam.builder()
            .toolCallId(call.asFunction().id())
            .contentAsJson(getWeather(args.city)) // your function
            .build());
    }
}

يحتفظ الـ builder بالمحادثة كاملة: تضيف كل دورة رسالة المساعد مع استدعاءات أدواتها، ثم رسالة أداة واحدة لكل استدعاء، وتُرسل كل شيء من جديد. تصبح حقول class الأداة خصائص المخطط، وأضف @JsonPropertyDescription إلى أي حقل لتخبر النموذج بمعناه. حدّد عدد التكرارات في كود الإنتاج حتى لا يدخل نموذج يواصل استدعاء الأدوات في حلقة لا تنتهي. راجع استدعاء الأدوات.

المخرجات المنظمة

مرّر class إلى responseFormat، فيولّد SDK منه مخطط JSON Schema صارمًا ويحلل محتوى كل choice إلى كائن منه. استخدم نموذجًا يُدرج structured_outputs أو response_format ضمن supported_parameters:

static class Person {
    public String name;
    public int born;
    public String city;
}

StructuredChatCompletionCreateParams<Person> params = ChatCompletionCreateParams.builder()
    .model("openai/gpt-5-mini")
    .responseFormat(Person.class)
    .addUserMessage("Extract: Ada Lovelace, born 1815 in London.")
    .build();

client.chat().completions().create(params).choices().stream()
    .flatMap(choice -> choice.message().content().stream())
    .forEach(person -> System.out.println(person.name + " " + person.born));

راجع المخرجات المنظمة.

إدخال الصور

import java.util.List;

ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
    .model("google/gemini-2.5-flash")
    .addUserMessageOfArrayOfContentParts(List.of(
        ChatCompletionContentPart.ofText(ChatCompletionContentPartText.builder()
            .text("What is in this picture?").build()),
        ChatCompletionContentPart.ofImageUrl(ChatCompletionContentPartImage.builder()
            .imageUrl(ChatCompletionContentPartImage.ImageUrl.builder()
                .url("https://example.com/photo.jpg") // or a data:image/png;base64,... URL
                .build())
            .build())))
    .build();

راجع الرؤية والملفات.

معاملات إضافية

حقول البوابة التي ليس لها setter مُنمَّط (reasoning وprovider وmodels) تمر عبر putAdditionalBodyProperty:

import com.openai.core.JsonValue;
import java.util.Map;

ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
    .model("anthropic/claude-sonnet-4.5")
    .addUserMessage("Prove there are infinitely many primes.")
    .putAdditionalBodyProperty("reasoning", JsonValue.from(Map.of("effort", "high")))
    .build();

الأخطاء

تُطلق الاستجابات غير الناجحة (غير 2xx) استثناءات من فئات فرعية لـ OpenAIServiceException، وتكشف الحالة والترويسات:

import com.openai.errors.OpenAIServiceException;

try {
    client.chat().completions().create(params);
} catch (OpenAIServiceException e) {
    if (e.statusCode() == 402) {
        System.err.println("Balance too low, add funds (insufficient_balance)");
    } else if (e.statusCode() == 429) {
        System.err.println("Rate limited, retry after " + e.headers().values("Retry-After") + "s");
    } else {
        throw e;
    }
}

راجع الأخطاء.

المهلات وإعادة المحاولة

يعيد العميل افتراضيًا محاولة أخطاء الاتصال والطلبات التي تنتهي بـ 408 و409 و429 و5xx مرتين مع تراجع أُسّي. اضبط العدد والمهلة في الـ builder، أو لكل طلب:

import com.openai.core.RequestOptions;
import java.time.Duration;

OpenAIClient client = OpenAIOkHttpClient.builder()
    .baseUrl("https://api14.com/api/v1")
    .apiKey(System.getenv("API14_API_KEY"))
    .maxRetries(4)
    .timeout(Duration.ofSeconds(60))
    .build();

client.chat().completions().create(params,
    RequestOptions.builder().timeout(Duration.ofMinutes(5)).build());

تنطبق مهلة الـ builder على كل محاولة. قد تستغرق طلبات الاستدلال الطويلة دقائق، فامنحها مهلة أطول لكل طلب أو استخدم البث. إعادة المحاولة لا تفيد مع daily_limit_reached أو insufficient_balance، فاعترض RateLimitException وافحص رمز الخطأ قبل جدولة محاولة أخرى. راجع حدود الطلبات.

كل القدرات

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api14.com/api/v1",
  apiKey: process.env.API14_API_KEY,
});

const result = await client.chat.completions.create({
  "model": "openai/gpt-5-mini",
  "messages": [
    {
      "role": "user",
      "content": "Explain vector databases in two sentences."
    }
  ]
});
console.log(result.choices[0].message.content);