نمونه API در زبان‌های برنامه‌نویسی

در زبان‌هایی که SDK رسمی OpenAI وجود دارد، همان SDK به Base URL چابکان متصل شده است. زبان‌های بدون SDK رسمی در بخش جداگانه با برچسب Community آمده‌اند.

این مثال‌ها برای چه پروژه‌هایی هستند؟

اگر می‌خواهید مدل هوش مصنوعی را مستقیماً داخل backend، ابزار خط فرمان، worker، بات یا سرویس سازمانی خود فراخوانی کنید، از نمونه زبان پروژه‌تان شروع کنید. همه مثال‌ها سه تنظیم مشترک دارند: API Key از environment خوانده می‌شود، base_url روی چابکان قرار می‌گیرد و Model ID از پنل انتخاب می‌شود.

استفاده از SDK رسمی مزایایی مانند typeهای درخواست و پاسخ، مدیریت streaming، timeout و retry متناسب با همان زبان دارد. با این حال API سازگار به این معنی نیست که تمام قابلیت‌های اختصاصی هر provider یا هر نسخه SDK روی همه مدل‌ها یکسان است؛ قابلیت‌هایی مانند Responses، tools، vision و structured output را پیش از production جداگانه آزمایش کنید.

برای شروع سریع فقط بخش زبان خود را اجرا کنید. برای مکالمه چندمرحله‌ای، هم‌زمانی و ابزارخوانی کامل به مثال‌های پیشرفته API بروید.

وضعیت کتابخانه‌ها

زبان	کتابخانه	وضعیت
Python	openai	رسمی OpenAI
JavaScript / TypeScript	openai	رسمی OpenAI
Go	github.com/openai/openai-go/v3	رسمی OpenAI
Java	com.openai:openai-java	رسمی OpenAI
C# / .NET	OpenAI	رسمی OpenAI
Ruby	openai	رسمی OpenAI
PHP	openai-php/client	Community
Rust	async-openai	Community
Kotlin / Android	SDK رسمی Java	قابل استفاده روی JVM

فهرست رسمی و community در OpenAI Docs نگهداری می‌شود.

تنظیمات مشترک

macOS، Linux و WSL:

export CHABOKAN_AI_API_KEY="sk-chbk-کلید-واقعی-شما"
export CHABOKAN_AI_MODEL="openai/gpt-4o-mini"

Windows PowerShell:

$env:CHABOKAN_AI_API_KEY = "sk-chbk-کلید-واقعی-شما"
$env:CHABOKAN_AI_MODEL = "openai/gpt-4o-mini"

Model ID بالا نمونه است. شناسه معتبر را از پنل یا GET /v1/models کپی کنید.

Python با SDK رسمی OpenAI

نصب

python -m pip install -U openai

Chat Completions

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CHABOKAN_AI_API_KEY"],
    base_url="https://ai.chabokan.net/v1",
    timeout=60,
    max_retries=2,
)

completion = client.chat.completions.create(
    model=os.environ["CHABOKAN_AI_MODEL"],
    messages=[
        {"role": "developer", "content": "پاسخ را کوتاه و فارسی بنویس."},
        {"role": "user", "content": "API چیست؟"},
    ],
)

print(completion.choices[0].message.content)

Responses API

response = client.responses.create(
    model=os.environ["CHABOKAN_AI_MODEL"],
    instructions="پاسخ را کوتاه و فارسی بنویس.",
    input="API چیست؟",
)

print(response.output_text)

سازگاری Responses به مدل وابسته است؛ ابتدا با یک درخواست ساده آزمایش کنید.

JavaScript و TypeScript با SDK رسمی OpenAI

نصب

npm install openai

کد Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CHABOKAN_AI_API_KEY,
  baseURL: "https://ai.chabokan.net/v1",
  timeout: 60_000,
  maxRetries: 2,
});

const completion = await client.chat.completions.create({
  model: process.env.CHABOKAN_AI_MODEL,
  messages: [
    { role: "developer", content: "پاسخ را کوتاه و فارسی بنویس." },
    { role: "user", content: "API چیست؟" },
  ],
});

console.log(completion.choices[0]?.message?.content ?? "");

همین package در Deno، Bun، Cloudflare Workers و server runtimeهای سازگار قابل استفاده است. API Key را در کد مرورگر قرار ندهید.

Go با SDK رسمی OpenAI

نصب

go get github.com/openai/openai-go/v3

کد

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/option"
)

func main() {
	client := openai.NewClient(
		option.WithAPIKey(os.Getenv("CHABOKAN_AI_API_KEY")),
		option.WithBaseURL("https://ai.chabokan.net/v1"),
	)

	completion, err := client.Chat.Completions.New(
		context.Background(),
		openai.ChatCompletionNewParams{
			Model: os.Getenv("CHABOKAN_AI_MODEL"),
			Messages: []openai.ChatCompletionMessageParamUnion{
				openai.DeveloperMessage("پاسخ را کوتاه و فارسی بنویس."),
				openai.UserMessage("API چیست؟"),
			},
		},
	)
	if err != nil {
		panic(err)
	}

	fmt.Println(completion.Choices[0].Message.Content)
}

Java با SDK رسمی OpenAI

نصب با Maven

نسخه را با نسخه جاری Java SDK رسمی تطبیق دهید:

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

کد

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 final class Main {
    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.builder()
            .apiKey(System.getenv("CHABOKAN_AI_API_KEY"))
            .baseUrl("https://ai.chabokan.net/v1")
            .build();

        ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
            .model(System.getenv("CHABOKAN_AI_MODEL"))
            .addDeveloperMessage("پاسخ را کوتاه و فارسی بنویس.")
            .addUserMessage("API چیست؟")
            .build();

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

SDK Java متغیرهای OPENAI_API_KEY و OPENAI_BASE_URL را نیز می‌خواند. نمونه بالا متغیر اختصاصی چابکان را صریحاً مصرف می‌کند تا با اتصال دیگر تداخل نداشته باشد.

C# و .NET با SDK رسمی OpenAI

نصب

dotnet add package OpenAI

کد

using OpenAI;
using OpenAI.Chat;
using System.ClientModel;

string apiKey = Environment.GetEnvironmentVariable("CHABOKAN_AI_API_KEY")
    ?? throw new InvalidOperationException("CHABOKAN_AI_API_KEY is required");
string model = Environment.GetEnvironmentVariable("CHABOKAN_AI_MODEL")
    ?? throw new InvalidOperationException("CHABOKAN_AI_MODEL is required");

var options = new OpenAIClientOptions {
    Endpoint = new Uri("https://ai.chabokan.net/v1"),
};

var client = new ChatClient(
    model: model,
    credential: new ApiKeyCredential(apiKey),
    options: options
);

ChatCompletion completion = await client.CompleteChatAsync([
    new DeveloperChatMessage("پاسخ را کوتاه و فارسی بنویس."),
    new UserChatMessage("API چیست؟"),
]);

Console.WriteLine(completion.Content[0].Text);

Ruby با SDK رسمی OpenAI

نصب

# Gemfile
gem "openai"

bundle install

کد

require "bundler/setup"
require "openai"

client = OpenAI::Client.new(
  api_key: ENV.fetch("CHABOKAN_AI_API_KEY"),
  base_url: "https://ai.chabokan.net/v1",
  timeout: 60,
  max_retries: 2
)

completion = client.chat.completions.create(
  model: ENV.fetch("CHABOKAN_AI_MODEL"),
  messages: [
    { role: :developer, content: "پاسخ را کوتاه و فارسی بنویس." },
    { role: :user, content: "API چیست؟" }
  ]
)

puts completion.choices.fetch(0).message.content

SDK رسمی فعلی Ruby به Ruby 3.3 یا جدیدتر نیاز دارد.

PHP با کتابخانه Community

OpenAI فعلاً SDK رسمی PHP منتشر نمی‌کند. این نمونه از openai-php/client استفاده می‌کند.

composer require openai-php/client

<?php

require __DIR__ . '/vendor/autoload.php';

$client = OpenAI::factory()
    ->withApiKey(getenv('CHABOKAN_AI_API_KEY'))
    ->withBaseUri('https://ai.chabokan.net/v1')
    ->make();

$completion = $client->chat()->create([
    'model' => getenv('CHABOKAN_AI_MODEL'),
    'messages' => [
        ['role' => 'developer', 'content' => 'پاسخ را کوتاه و فارسی بنویس.'],
        ['role' => 'user', 'content' => 'API چیست؟'],
    ],
]);

echo $completion->choices[0]->message->content . PHP_EOL;

در پروژه حساس، نسخه package را pin و changelog آن را بررسی کنید. گزینه بدون dependency، cURL داخلی PHP است.

Rust با کتابخانه Community

OpenAI فعلاً SDK رسمی Rust منتشر نمی‌کند. نمونه زیر از async-openai استفاده می‌کند.

cargo add async-openai tokio

use async_openai::{
    config::OpenAIConfig,
    types::{ChatCompletionRequestUserMessageArgs, CreateChatCompletionRequestArgs},
    Client,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = OpenAIConfig::new()
        .with_api_key(std::env::var("CHABOKAN_AI_API_KEY")?)
        .with_api_base("https://ai.chabokan.net/v1");
    let client = Client::with_config(config);

    let request = CreateChatCompletionRequestArgs::default()
        .model(std::env::var("CHABOKAN_AI_MODEL")?)
        .messages([ChatCompletionRequestUserMessageArgs::default()
            .content("API چیست؟")
            .build()?
            .into()])
        .build()?;

    let completion = client.chat().create(request).await?;
    println!("{}", completion.choices[0].message.content.as_deref().unwrap_or(""));
    Ok(())
}

Kotlin و Android

در backend نوشته‌شده با Kotlin/JVM می‌توانید SDK رسمی Java یعنی com.openai:openai-java را استفاده کنید. Base URL با baseUrl(...) تعیین می‌شود.

API Key را داخل APK یا اپ موبایل قرار ندهید. اپ باید backend خودتان را صدا بزند و backend درخواست چابکان را انجام دهد.

مقایسه تنظیم Base URL

SDK	تنظیم چابکان
Python	base_url="https://ai.chabokan.net/v1"
JavaScript	baseURL: "https://ai.chabokan.net/v1"
Go	option.WithBaseURL(...)
Java	.baseUrl(...)
.NET	OpenAIClientOptions.Endpoint
Ruby	base_url: ...
PHP community	withBaseUri(...)
Rust community	with_api_base(...)

روش آزمون همه زبان‌ها

1. GET /v1/models را با همان کلید اجرا کنید.
2. Model ID را عیناً از خروجی بردارید.
3. ابتدا درخواست ساده بدون streaming، tools یا تصویر بفرستید.
4. قابلیت‌های پیشرفته را یکی‌یکی فعال کنید.
5. اگر cURL موفق و SDK ناموفق است، Base URL و نسخه package را بررسی کنید.

خطا	اقدام
401	کلید، environment و فعال‌بودن آن را بررسی کنید
402	اعتبار یا سقف ماهانه کلید را بررسی کنید
404	Base URL باید یک /v1 داشته باشد و Model ID دقیق باشد
429	concurrency را کاهش و retry با backoff انجام دهید
parse error	status code و بدنه خطا را پیش از خواندن اولین choice ببینید

برای streaming، async، tools، تصویر و Responses به مثال‌های پیشرفته API بروید.

منابع: SDKهای رسمی و community در OpenAI Docs، Python SDK، JavaScript SDK، Java SDK، Ruby SDK