API فری‌جی‌پی‌تی — یک کلید، ده‌ها مدل

شروع سریع در ۳ گام

از صفر تا اولین پاسخ، کمتر از پنج دقیقه.

آدرس پایه و احراز هویت

آدرس پایهٔ رسمی سرویس:

https://api.freegpt.ir/v1

آدرس جایگزین (در صورت نیاز، همان سرویس): https://freegpt.ir/api/v1/gateway/v1

احراز هویت دقیقاً مثل OpenAI است: کلید را در هدر Authorization به‌صورت Bearer بفرستید.

Authorization: Bearer fg-YOUR_KEY

اندپوینت‌های موجود (سازگار با OpenAI):

• POST /v1/chat/completions — گفت‌وگو و تولید متن (با پشتیبانی از stream)
• POST /v1/embeddings — تبدیل متن به بردار (برای جستجوی معنایی و ایندکس کد)
• GET /v1/models — فهرست مدل‌های در دسترس

مدل‌ها و قیمت

به‌جای نام برند هر شرکت، ما «لِین»های ساده داریم؛ هر لِین بهترین مدل در دسترس را خودکار انتخاب می‌کند (و اگر یکی در دسترس نبود، به مدل جایگزین می‌رود). شما فقط نام لِین را به‌عنوان model بفرستید.

نمونه‌کدهای پایه

هر کتابخانهٔ رسمی OpenAI کار می‌کند؛ کافی است base_url و کلید را تنظیم کنید.

from openai import OpenAI

client = OpenAI(
    api_key="fg-YOUR_KEY",
    base_url="https://api.freegpt.ir/v1",
)

resp = client.chat.completions.create(
    model="balanced",
    messages=[{"role": "user", "content": "سلام! خودت را معرفی کن."}],
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "fg-YOUR_KEY",
  baseURL: "https://api.freegpt.ir/v1",
});

const resp = await client.chat.completions.create({
  model: "balanced",
  messages: [{ role: "user", content: "سلام! خودت را معرفی کن." }],
});
console.log(resp.choices[0].message.content);

curl https://api.freegpt.ir/v1/chat/completions \
  -H "Authorization: Bearer fg-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "balanced",
    "messages": [{"role": "user", "content": "سلام!"}]
  }'

<?php
$ch = curl_init("https://api.freegpt.ir/v1/chat/completions");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer fg-YOUR_KEY",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "model" => "balanced",
    "messages" => [["role" => "user", "content" => "سلام!"]],
  ]),
]);
$out = json_decode(curl_exec($ch), true);
echo $out["choices"][0]["message"]["content"];

پاسخ جریانی (Streaming)

برای دریافت پاسخ کلمه‌به‌کلمه، کافی است "stream": true را اضافه کنید (مثل OpenAI).

stream = client.chat.completions.create(
    model="balanced",
    messages=[{"role": "user", "content": "یک شعر کوتاه بگو"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

موارد کاربرد

چند نمونه از چیزهایی که می‌توانید با همین یک کلید بسازید — به‌همراه مدل پیشنهادی.

استخراج دادهٔ ساختاریافته (JSON)

برای استخراج خروجی ماشین‌خوان (مثلاً از متن آزاد به JSON)، از response_format استفاده کنید — درست مثل OpenAI.

from openai import OpenAI
client = OpenAI(api_key="fg-YOUR_KEY", base_url="https://api.freegpt.ir/v1")

r = client.chat.completions.create(
    model="balanced",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "نام و شماره تماس را به صورت JSON با کلیدهای name و phone برگردان."},
        {"role": "user", "content": "سلام، من علی هستم، شماره‌ام ۰۹۱۲۳۴۵۶۷۸۹ است."},
    ],
)
print(r.choices[0].message.content)   # {"name": "علی", "phone": "09123456789"}

فریم‌ورک‌ها و کتابخانه‌ها

فریم‌ورک‌های محبوب هوش مصنوعی هم آدرس پایهٔ سفارشی می‌پذیرند.

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="premium",
    base_url="https://api.freegpt.ir/v1",
    api_key="fg-YOUR_KEY",
)
print(llm.invoke("سلام!").content)

from llama_index.llms.openai_like import OpenAILike

llm = OpenAILike(
    model="premium",
    api_base="https://api.freegpt.ir/v1",
    api_key="fg-YOUR_KEY",
    is_chat_model=True,
)
print(llm.complete("سلام!"))

import { createOpenAI } from "@ai-sdk/openai";
import { generateText } from "ai";

const fg = createOpenAI({
  baseURL: "https://api.freegpt.ir/v1",
  apiKey: process.env.FREEGPT_KEY,
});
const { text } = await generateText({ model: fg("balanced"), prompt: "سلام!" });
console.log(text);

import openai "github.com/sashabaranov/go-openai"

cfg := openai.DefaultConfig("fg-YOUR_KEY")
cfg.BaseURL = "https://api.freegpt.ir/v1"
client := openai.NewClientWithConfig(cfg)
// client.CreateChatCompletion(... Model: "balanced" ...)

محیط‌های برنامه‌نویسی

کلید فری‌جی‌پی‌تی را به ویرایشگر کد خود وصل کنید و از تکمیل کد و چت داخل ویرایشگر استفاده کنید.

{
  "models": [{
    "title": "FreeGPT Balanced",
    "provider": "openai",
    "model": "balanced",
    "apiBase": "https://api.freegpt.ir/v1",
    "apiKey": "fg-YOUR_KEY"
  }],
  "tabAutocompleteModel": {
    "title": "FreeGPT Coding",
    "provider": "openai",
    "model": "coding",
    "apiBase": "https://api.freegpt.ir/v1",
    "apiKey": "fg-YOUR_KEY"
  },
  "embeddingsProvider": {
    "provider": "openai",
    "model": "embed",
    "apiBase": "https://api.freegpt.ir/v1",
    "apiKey": "fg-YOUR_KEY"
  }
}

{
  "language_models": {
    "openai": {
      "api_url": "https://api.freegpt.ir/v1",
      "available_models": [
        { "name": "balanced", "max_tokens": 32000 },
        { "name": "premium", "max_tokens": 128000 }
      ]
    }
  }
}

اجنت‌های کد و ترمینال

اجنت‌هایی که در ترمینال یا مستقل اجرا می‌شوند و خودشان فایل‌ها را می‌خوانند و ویرایش می‌کنند.

aider

aider یک جفت‌برنامه‌نویس هوش مصنوعی در ترمینال است. با متغیرهای محیطی یا فلگ‌ها وصلش کنید:

# روش ۱: متغیر محیطی
export OPENAI_API_BASE="https://api.freegpt.ir/v1"
export OPENAI_API_KEY="fg-YOUR_KEY"
aider --model openai/premium

# روش ۲: مستقیم با فلگ
aider --openai-api-base https://api.freegpt.ir/v1 \
      --openai-api-key fg-YOUR_KEY \
      --model openai/premium

OpenClaw و اجنت‌های مشابه

OpenClaw و اجنت‌های ترمینالی مشابه (که با مدل‌های سازگار با OpenAI کار می‌کنند) را با همان دو متغیر محیطی بالا تنظیم کنید. معمولاً در فایل پیکربندی اجنت یک بخش «provider» سازگار با OpenAI وجود دارد:

{
  "provider": "openai",
  "baseUrl": "https://api.freegpt.ir/v1",
  "apiKey": "fg-YOUR_KEY",
  "model": "premium"
}

برای کارهای اجنتی سنگین (که چندین درخواست پشت‌سرهم می‌زنند) حتماً موجودی کافی در کیف پول داشته باشید و در صورت تمایل برای آن کلید یک «سقف ماهانه» تعیین کنید تا هزینه کنترل‌شده بماند.

وردپرس

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

چت‌بات وب‌سایت

برای افزودن یک دستیار گفت‌وگو به سایت، هرگز کلید را در کد سمت مرورگر نگذارید (هر کسی می‌تواند ببیندش). به‌جای آن یک «پراکسی» کوچک روی سرور خودتان بگذارید که کلید را پنهان نگه می‌دارد.

۱) پراکسی سمت سرور (نمونهٔ Node / Express)

import express from "express";
import OpenAI from "openai";

const app = express();
app.use(express.json());
const client = new OpenAI({
  apiKey: process.env.FREEGPT_KEY,            // کلید روی سرور می‌ماند
  baseURL: "https://api.freegpt.ir/v1",
});

app.post("/chat", async (req, res) => {
  const r = await client.chat.completions.create({
    model: "balanced",
    messages: [
      { role: "system", content: "تو دستیار پشتیبانی سایت ما هستی. کوتاه و مودب پاسخ بده." },
      { role: "user", content: req.body.message },
    ],
  });
  res.json({ reply: r.choices[0].message.content });
});
app.listen(3000);

۲) ویجت سمت مرورگر (به پراکسی شما وصل می‌شود)

<script>
async function ask(message) {
  const r = await fetch("/chat", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ message }),
  });
  const data = await r.json();
  return data.reply;
}
// نمونه: ask("ساعات کاری شما چیست؟").then(console.log);
</script>

اتوماسیون و سرویس‌های CRM

با ابزارهای اتوماسیون می‌توانید هوش مصنوعی را به CRM، فرم‌ها، ایمیل و هر سیستم دیگری وصل کنید — بدون کدنویسی.

n8n

1. یک Credential از نوع OpenAI بسازید.
2. در فیلد API Key کلید fg-… و در Base URL آدرس https://api.freegpt.ir/v1 را بگذارید.
3. در نود OpenAI، مدل را balanced یا premium انتخاب کنید.

Make، Zapier و CRMهای عمومی (روش HTTP)

اگر سرویس شما نود آمادهٔ OpenAI ندارد، از یک ماژول «HTTP Request» استفاده کنید:

POST https://api.freegpt.ir/v1/chat/completions
Headers:
  Authorization: Bearer fg-YOUR_KEY
  Content-Type: application/json
Body (JSON):
{
  "model": "balanced",
  "messages": [
    { "role": "system", "content": "خلاصهٔ این پیام مشتری را در یک جمله بنویس." },
    { "role": "user", "content": "{{متن پیام مشتری از CRM}}" }
  ]
}

پاسخ در مسیر choices[0].message.content است؛ همان را در فیلد CRM ذخیره کنید. کاربردهای رایج: خلاصه‌سازی تیکت، دسته‌بندی خودکار سرنخ‌ها، پاسخ پیش‌نویس، و تحلیل احساس مشتری.

امبدینگ و جستجوی معنایی

برای جستجوی معنایی، پایگاه دانش (RAG) و ایندکس‌کردن کد، از اندپوینت امبدینگ با مدل embed استفاده کنید (چندزبانه و فارسی‌دوست).

from openai import OpenAI
client = OpenAI(api_key="fg-YOUR_KEY", base_url="https://api.freegpt.ir/v1")

vec = client.embeddings.create(
    model="embed",
    input=["متن اول برای ایندکس", "متن دوم"],
)
print(len(vec.data[0].embedding))   # طول بردار

همین مدل را می‌توانید به‌عنوان embeddingsProvider در Continue یا منبع امبدینگ در ابزارهای RAG تنظیم کنید تا کل پروژه/سند شما به‌صورت معنایی قابل‌جستجو شود.

عیب‌یابی خطاها

بدنهٔ خطا همیشه به‌صورت JSON و در قالب استاندارد OpenAI ({"error": {...}}) برمی‌گردد تا کتابخانه‌های رسمی آن را درست بفهمند.

محدودیت‌ها و نکات

• حسابداری مصرف: هزینه بر اساس مصرف واقعی توکن از کیف پول کسر می‌شود؛ در API همهٔ مدل‌ها (شامل مدل‌های پایه) هزینه دارند و بدون اعتبار کافی فراخوانی متوقف می‌شود (۴۰۲).
• محدودیت نرخ: برای جلوگیری از سوءاستفاده، هر کلید سقف نرخ درخواست در دقیقه دارد؛ در صورت عبور، پاسخ ۴۲۹ با هدر Retry-After برمی‌گردد.
• گزارش مصرف: در حساب کاربری برای هر کلید گزارش مصرف (تعداد، توکن، هزینه، تفکیک مدل و نمودار روزانه) در دسترس است.
• سقف ماهانهٔ هر کلید: هنگام ساخت کلید می‌توانید یک سقف ماهانه (به تومان) بگذارید؛ مصرف هر ماه از نو شمرده می‌شود.
• امنیت کلید: کلید کامل فقط یک‌بار نمایش داده می‌شود. اگر لو رفت، از حساب کاربری باطلش کنید و کلید تازه بسازید.
• چند کلید: برای هر پروژه یک کلید جدا بسازید (تا ۲۰ کلید فعال) تا مصرف و امنیت هرکدام مستقل باشد.
• سازگاری: هر کتابخانه یا ابزاری که با OpenAI کار می‌کند، با تغییر آدرس پایه با ما هم کار می‌کند.