API فری‌جی‌پی‌تی — یک کلید برای مدل‌های عمومی

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

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

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

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

https://api.freegpt.ir/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 یا گزینهٔ bge-m3 استفاده کنید. موجودبودن هر دو نام را می‌توانید با GET /v1/models بررسی کنید.

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))   # طول بردار

یکی از مدل‌های embed یا bge-m3 را می‌توانید به‌عنوان embeddingsProvider در Continue یا منبع امبدینگ در ابزارهای RAG تنظیم کنید.

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

خطاهای gateway به‌صورت JSON سازگار با OpenAI و با ساختار زیر برمی‌گردند. برای تصمیم برنامه‌ای، فیلد error.code را بخوانید و برای نمایش فارسی از error.message_fa استفاده کنید.

{
  "error": {
    "message": "Insufficient account credit.",
    "message_fa": "اعتبار حساب برای این درخواست کافی نیست.",
    "type": "billing_error",
    "code": "insufficient_credit"
  }
}

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

• حسابداری مصرف: هر فراخوانی پیش از اجرا به اعتبار کافی نیاز دارد؛ هزینهٔ تأییدشدهٔ مصرف از کیف پول کسر و نبود اعتبار با ۴۰۲ متوقف می‌شود.
• نوع ورودی: مدل‌های گفت‌وگو در API عمومی فقط ورودی متنی می‌پذیرند؛ تصویر، صوت و ویدئو در این نسخه پشتیبانی نمی‌شود.
• محدودیت نرخ: برای جلوگیری از سوءاستفاده، هر کلید سقف نرخ درخواست در دقیقه دارد؛ در صورت عبور، پاسخ ۴۲۹ با هدر Retry-After برمی‌گردد.
• گزارش مصرف: در حساب کاربری برای هر کلید گزارش مصرف (تعداد، توکن، هزینه، تفکیک مدل و نمودار روزانه) در دسترس است.
• سقف ماهانهٔ هر کلید: هنگام ساخت یا بعداً با «ویرایش»، سقف ماهانه را به تومان تعیین کنید. داشبورد مصرف ماه جاری، مانده و تاریخ بازنشانی را نشان می‌دهد؛ مصرف هر ماه از نو شمرده می‌شود.
• Scope: دسترسی‌های chat و embeddings مستقل‌اند و می‌توانید برای اصل کمترین دسترسی فقط مورد لازم را فعال کنید.
• امنیت کلید: کلید کامل فقط یک‌بار نمایش داده می‌شود. اگر لو رفت، از حساب کاربری باطلش کنید و کلید تازه بسازید.
• چند کلید: برای هر پروژه یک کلید جدا بسازید (تا ۲۰ کلید فعال) تا مصرف و امنیت هرکدام مستقل باشد.
• سازگاری: ابزار باید آدرس پایهٔ سفارشی و یکی از اندپوینت‌های ارائه‌شدهٔ chat/completions، embeddings یا models را پشتیبانی کند.