پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

مرجع API v1beta SDK Google GenAI

API v1beta دسترسی بومی به مدل‌های Gemini گوگل را با استفاده از SDK رسمی GenAI گوگل و طرحواره یا اسکیمای API آن فراهم می‌کند. این نقطه پایانی به شما امکان استفاده از متدهای بومی گوگل از جمله generateContent، streamGenerateContent، embedContent، batchEmbedContents، countTokens و predict از طریق زیرساخت AvalAI را می‌دهد.

مستندات رسمی: برای جزئیات کامل API Gemini، به مستندات رسمی Gemini API گوگل مراجعه کنید.

URL پایه

https://api.avalai.ir

مهم

هنگام استفاده از SDK Google GenAI با AvalAI، از https://api.avalai.ir به عنوان URL پایه استفاده کنید (بدون /v1). این با نقاط پایانی سازگار با OpenAI که از /v1 استفاده می‌کنند، متفاوت است.

احراز هویت

API v1beta از دو روش احراز هویت پشتیبانی می‌کند:

روش ۱: Bearer Token (توصیه شده)

http

Authorization: Bearer $AVALAI_API_KEY

روش ۲: هدر بومی گوگل

http

x-goog-api-key: YOUR_AVALAI_API_KEY

مدل‌های پشتیبانی شده

API v1beta منحصرا از مدل‌های گوگل پشتیبانی می‌کند. می‌توانید از هر مدل Gemini یا Imagen موجود در AvalAI استفاده کنید:

مدل‌های Gemini (متن، بینایی، صوتی)

gemini-3.5-flash
gemini-3.1-pro-preview
gemini-3.1-flash-lite
gemini-3.1-flash-lite-preview
gemini-2.5-pro
gemini-2.5-flash
gemini-robotics-er-1.5-preview (رباتیک)
gemini-2.5-pro-preview-tts (تبدیل متن به گفتار)
gemini-2.5-flash-preview-tts (تبدیل متن به گفتار)

مدل‌های Imagen (تولید تصویر)

imagen-4.0-generate-001
imagen-4.0-ultra-generate-001
imagen-4.0-fast-generate-001

برای فهرست کامل مدل‌های موجود، مستندات مدل‌های گوگل را ببینید.

نقاط پایانی

توجه

تمام نقاط پایانی کاملا با مستندات رسمی Gemini API گوگل سازگار هستند. برای مثال‌های اضافی و توضیحات دقیق پارامترها به مستندات رسمی مراجعه کنید.

تولید محتوا

تولید محتوای متنی با استفاده از مدل Gemini.

http

POST /v1beta/models/{model}:generateContent

پارامترها

پارامتر	نوع	ضروری	توضیحات
`model`	string	بله	مدل Gemini مورد استفاده (مثل `gemini-3.5-flash`)

بدنه درخواست

فیلد	نوع	ضروری	توضیحات
`contents`	array	بله	آرایه‌ای از اشیا محتوا که مکالمه را نمایش می‌دهد
`system_instruction`	object	خیر	دستورالعمل سیستمی برای کنترل رفتار مدل
`generationConfig`	object	خیر	پیکربندی برای تولید
`safetySettings`	array	خیر	تنظیمات امنیتی برای فیلتر محتوا
`tools`	array	خیر	ابزارهای در دسترس مدل

شی محتوا

فیلد	نوع	ضروری	توضیحات
`parts`	array	بله	آرایه‌ای از قسمت‌ها (متن، تصاویر و غیره)
`role`	string	بله	نقش محتوا (`user`، `model`)

نکته مهم

هنگام استفاده از API بومی Gemini v1beta، فقط نقش‌های user و model در آرایه contents پشتیبانی می‌شوند. نقش user برای پیام‌های کاربر و نقش model برای پاسخ‌های دستیار در تاریخچه مکالمه است. برای دستورالعمل‌های سطح سیستم، از پارامتر جداگانه system_instruction استفاده کنید.

شی دستورالعمل سیستمی

فیلد	نوع	ضروری	توضیحات
`parts`	array	بله	آرایه‌ای از قسمت‌ها حاوی متن دستورالعمل سیستمی

پیکربندی تولید

فیلد	نوع	توضیحات
`maxOutputTokens`	integer	حداکثر تعداد توکن‌های قابل تولید
`temperature`	number	کنترل تصادفی بودن (۰.۰ تا ۲.۰)
`topP`	number	کنترل تنوع از طریق نمونه‌برداری nucleus
`topK`	integer	کنترل تنوع از طریق نمونه‌برداری top-k
`stopSequences`	array	دنباله‌هایی که تولید باید در آنجا متوقف شود
`thinkingConfig`	object	پیکربندی رفتار تفکر (سطوح تفکر Gemini 3.5/3.1 و بودجه‌های Gemini 2.5)
`responseModalities`	array	حالت‌های پاسخ (برای TTS: `["AUDIO"]`)
`speechConfig`	object	پیکربندی تبدیل متن به گفتار

پیکربندی گفتار (speechConfig)

فیلد	نوع	توضیحات
`voiceConfig`	object	پیکربندی صدای تک گوینده
`multiSpeakerVoiceConfig`	object	پیکربندی صدای چند گوینده

پیکربندی صدای تک گوینده (voiceConfig)

فیلد	نوع	توضیحات
`prebuiltVoiceConfig`	object	استفاده از صدای از پیش ساخته شده

پیکربندی صدای از پیش ساخته شده (prebuiltVoiceConfig)

فیلد	نوع	توضیحات
`voiceName`	string	نام صدا (`Kore`, `Charon`, `Puck`, `Fenrir`)

پیکربندی صدای چند گوینده (multiSpeakerVoiceConfig)

فیلد	نوع	توضیحات
`speakerVoiceConfigs`	array	آرایه‌ای از پیکربندی‌های صدای گوینده

پیکربندی صدای گوینده (speakerVoiceConfig)

فیلد	نوع	توضیحات
`speaker`	string	نام گوینده (مطابق با متن)
`voiceConfig`	object	پیکربندی صدا برای این گوینده

پیکربندی تفکر (مدل‌های Gemini)

فیلد	نوع	توضیحات
`thinkingLevel`	string	عمق استدلال برای مدل‌های Gemini 3.5/3.1 (`low`، `medium`، `high`)
`thinkingBudget`	integer	بودجه قدیمی تفکر Gemini 2.5 Flash بر حسب توکن (۰ تفکر را غیرفعال می‌کند)

نمونه درخواست

bash

curl -X POST 'https://api.avalai.ir/v1beta/models/gemini-3.5-flash:generateContent' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $AVALAI_API_KEY' \
  -d '{
	"contents": [
		{
			"parts": [
				{
					"text": "داستان کوتاهی درباره هوش مصنوعی بنویس."
				}
			],
			"role": "user"
		}
	],
	"generationConfig": {
		"maxOutputTokens": 1000,
		"temperature": 0.7
	}
}'

نمونه با دستورالعمل‌های سیستمی

اگر نیاز به ارائه دستورالعمل‌های سطح سیستم برای هدایت رفتار مدل دارید، از پارامتر system_instruction استفاده کنید:

bash

curl -i https://api.avalai.ir/v1beta/models/gemini-2.5-flash:generateContent \
  -H "x-goog-api-key: $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
	"system_instruction": {
		"parts": [
			{
				"text": "به فارسی بنویس"
			}
		]
	},
	"contents": [
		{
			"parts": [
				{
					"text": "داستان کوتاهی درباره هوش مصنوعی بنویس."
				}
			],
			"role": "user"
		}
	],
	"generationConfig": {
		"thinkingConfig": {
			"thinkingBudget": 0
		},
		"maxOutputTokens": 70,
		"stopSequences": [
			"عنوان"
		],
		"temperature": 1.0,
		"topP": 0.8,
		"topK": 10
	}
}'

نکته

API v1beta با مستندات رسمی API Gemini سازگار است. اگر تناقضی مشاهده کردید، لطفا با ما در t.me/AvalAISupport تماس بگیرید.

نمونه پاسخ

json

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "در سال ۲۰۴۵، دکتر سارا چن در برابر بزرگترین خلقت خود ایستاد..."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 150,
    "totalTokenCount": 162
  }
}

تولید محتوای جریانی

تولید محتوای متنی جریانی با استفاده از مدل Gemini.

http

POST /v1beta/models/{model}:streamGenerateContent

فرمت درخواست مشابه generateContent است، اما پاسخ به صورت Server-Sent Events جریانی می‌شود.

نمونه درخواست

bash

curl -X POST 'https://api.avalai.ir/v1beta/models/gemini-2.5-flash:streamGenerateContent' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $AVALAI_API_KEY' \
  -d '{
 "contents": [
 {
 "parts": [
 {
 "text": "Explain AI"
 }
 ],
 "role": "user"
 }
 ],
 "generationConfig": {
 "maxOutputTokens": 500
 }
 }'

نمونه پاسخ جریانی

[
    {
        "candidates": [
            {
                "content": {
                    "parts": [
                        {
                            "text": "An"
                        }
                    ],
                    "role": "model"
                }
            }
        ],
        "usageMetadata": {
            "promptTokenCount": 4,
            "totalTokenCount": 4,
            "promptTokensDetails": [
                {
                    "modality": "TEXT",
                    "tokenCount": 4
                }
            ]
        },
        "modelVersion": "gemini-2.5-flash",
        "responseId": "sOl_aKOWPIPxMTp1fDNn6QQ"
    },
    {
        "candidates": [
            {
                "content": {
                    "parts": [
                        {
                            "text": " broad term that can encompass a few different things:\n\n*   **AI-"
                        }
                    ],
                    "role": "model"
                }
            }
        ],
        "usageMetadata": {
            "promptTokenCount": 4,
            "totalTokenCount": 4,
            "promptTokensDetails": [
                {
                    "modality": "TEXT",
                    "tokenCount": 4
                }
            ]
        },
        "modelVersion": "gemini-2.5-flash",
        "responseId": "sOl_aKOWPIPxMTp1fDNn6QQ"
    },
    
    ...

    {
        "candidates": [
            {
                "content": {
                    "parts": [
                        {
                            "text": "\n\n**In summary, an AI sentence can either be a sentence created *by* an AI or a sentence being analyzed *by* an AI. It's a fundamental component of how AI interacts with and understands human language.**\n"
                        }
                    ],
                    "role": "model"
                },
                "finishReason": "STOP"
            }
        ],
        "usageMetadata": {
            "promptTokenCount": 3,
            "candidatesTokenCount": 571,
            "totalTokenCount": 574,
            "promptTokensDetails": [
                {
                    "modality": "TEXT",
                    "tokenCount": 3
                }
            ],
            "candidatesTokensDetails": [
                {
                    "modality": "TEXT",
                    "tokenCount": 571
                }
            ]
        },
        "modelVersion": "gemini-2.5-flash",
        "responseId": "sOl_aKOWPIPxMTp1fDNn6QQ"
    }
]

استفاده با SDK Google GenAI

Python

python

from google import genai
from google.genai.types import ContentDict, PartDict

# راه‌اندازی کلاینت
client = genai.Client(
    api_key="your-avalai-api-key", http_options={"base_url": "https://api.avalai.ir"}
)

# تولید محتوا
contents = ContentDict(parts=[PartDict(text="سلام، حال شما چطور است؟")], role="user")

response = await client.agenerate_content(
    contents=contents, model="gemini-2.5-flash", max_tokens=100
)

print(response)

جریان با Python

python

# تولید جریانی
response = await client.agenerate_content_stream(
    contents=contents, model="gemini-2.5-flash", max_tokens=500
)

async for chunk in response:
    print(chunk)

پشتیبانی چندوجهی

API v1beta از ورودی‌های چندوجهی شامل متن، تصاویر، صدا و ویدیو پشتیبانی می‌کند.

نمونه ورودی تصویر

python

# نکته: تصاویر باید برای مدل‌های Gemini به صورت base64 کدگذاری شوند
contents = ContentDict(
    parts=[
        PartDict(text="در این تصویر چه چیزی هست؟"),
        PartDict(
            inline_data={"mime_type": "image/jpeg", "data": "base64_encoded_image_data"}
        ),
    ],
    role="user",
)

response = await client.agenerate_content(contents=contents, model="gemini-2.5-flash")

پایه‌گذاری با جستجوی گوگل (Grounding with Google Search)

پایه‌گذاری با جستجوی گوگل مدل‌های Gemini را به محتوای وب بلادرنگ متصل می‌کند و با تمام زبان‌های موجود کار می‌کند. این امکان به Gemini اجازه می‌دهد پاسخ‌های دقیق‌تر ارائه دهد و منابع قابل تأیید را فراتر از تاریخ قطع دانش خود ذکر کند.

مزایای کلیدی

افزایش دقت واقعی: کاهش توهمات مدل با مبنا قرار دادن پاسخ‌ها بر اطلاعات دنیای واقعی
دسترسی به اطلاعات بلادرنگ: پاسخ به سؤالات درباره رویدادها و موضوعات اخیر
ارائه استنادات: ایجاد اعتماد کاربر با نمایش منابع ادعاهای مدل

نمونه درخواست

bash

curl "https://api.avalai.ir/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {"text": "چه کسی یورو ۲۰۲۴ را برد؟"}
        ]
      }
    ],
    "tools": [
      {
        "google_search": {}
      }
    ]
  }'

استفاده با SDK Google GenAI

Python

python

from google import genai
from google.genai import types

client = genai.Client(
    api_key="your-avalai-api-key",
    http_options={"api_version": "v1beta", "base_url": "https://api.avalai.ir"},
)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="چه کسی یورو ۲۰۲۴ را برد؟",
    config=types.GenerateContentConfig(
        tools=[types.Tool(google_search=types.GoogleSearch())]
    ),
)

print(response.text)

JavaScript

javascript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    apiKey: process.env.AVALAI_API_KEY,
    httpOptions: {"apiVersion": "v1beta", "baseUrl": "https://api.avalai.ir"}
});

const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: "چه کسی یورو ۲۰۲۴ را برد؟",
    config: {
        tools: [{ googleSearch: {} }]
    }
});

console.log(response.text);

نحوه کار پایه‌گذاری

وقتی ابزار google_search را فعال می‌کنید، مدل به طور خودکار کل گردش کار را مدیریت می‌کند:

تحلیل پرامپت: مدل پرامپت را تحلیل می‌کند و تعیین می‌کند که آیا جستجوی گوگل می‌تواند پاسخ را بهبود بخشد
جستجوی گوگل: در صورت نیاز، مدل به طور خودکار یک یا چند پرس‌وجوی جستجو تولید و اجرا می‌کند
پردازش نتایج جستجو: مدل نتایج جستجو را پردازش، اطلاعات را ترکیب و پاسخ را فرمول‌بندی می‌کند
پاسخ پایه‌گذاری‌شده: API یک پاسخ نهایی پایه‌گذاری‌شده بر نتایج جستجو با استنادات برمی‌گرداند

درک پاسخ پایه‌گذاری

هنگامی که یک پاسخ با موفقیت پایه‌گذاری می‌شود، پاسخ شامل یک فیلد groundingMetadata است:

json

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "اسپانیا یورو ۲۰۲۴ را برد و انگلستان را ۲-۱ در فینال شکست داد. این پیروزی چهارمین عنوان قهرمانی اروپای رکوردشکن اسپانیا را رقم زد."
          }
        ],
        "role": "model"
      },
      "groundingMetadata": {
        "webSearchQueries": [
          "برنده یورو ۲۰۲۴",
          "چه کسی یورو ۲۰۲۴ را برد"
        ],
        "searchEntryPoint": {
          "renderedContent": "<!-- HTML و CSS برای ویجت جستجو -->"
        },
        "groundingChunks": [
          {"web": {"uri": "https://...", "title": "aljazeera.com"}},

            {"web": {"uri": "https://...", "title": "uefa.com"}}

            ],
            "groundingSupports": [
              {
                "segment": {"startIndex": 0, "endIndex": 85, "text": "اسپانیا یورو ۲۰۲۴ را برد..."},
                "groundingChunkIndices": [0]
              },
              {
                "segment": {"startIndex": 86, "endIndex": 210, "text": "این پیروزی چهارمین..."},
                "groundingChunkIndices": [0, 1]
              }
            ]
          }
        }
      ]
    }

groundingMetadata شامل موارد زیر است:

فیلد	توضیحات
`webSearchQueries`	آرایه‌ای از پرس‌وجوهای جستجوی استفاده‌شده. مفید برای اشکال‌زدایی و درک فرآیند استدلال مدل
`searchEntryPoint`	شامل HTML و CSS برای رندر کردن پیشنهادات جستجوی مورد نیاز
`groundingChunks`	آرایه‌ای از اشیاء حاوی منابع وب (uri و title)
`groundingSupports`	آرایه‌ای از قطعات که متن پاسخ مدل را به منابع متصل می‌کند. هر قطعه یک بخش متنی (تعریف‌شده با startIndex و endIndex) را به یک یا چند groundingChunkIndices پیوند می‌دهد

نسبت‌دهی منابع با استنادات درون‌خطی

می‌توانید از فیلدهای groundingSupports و groundingChunks برای ایجاد استنادات درون‌خطی استفاده کنید:

python

def add_citations(response):
    text = response.text
    supports = response.candidates[0].grounding_metadata.grounding_supports
    chunks = response.candidates[0].grounding_metadata.grounding_chunks

    # مرتب‌سازی supports بر اساس end_index به صورت نزولی برای جلوگیری از مشکلات جابجایی هنگام درج
    sorted_supports = sorted(supports, key=lambda s: s.segment.end_index, reverse=True)

    for support in sorted_supports:
        end_index = support.segment.end_index
        if support.grounding_chunk_indices:
            # ایجاد رشته استناد مانند [1](link1)[2](link2)
            citation_links = []
            for i in support.grounding_chunk_indices:
                if i < len(chunks):
                    uri = chunks[i].web.uri
                    citation_links.append(f"[{i + 1}]({uri})")

            citation_string = ", ".join(citation_links)
            text = text[:end_index] + citation_string + text[end_index:]

    return text


# استفاده با پاسخ پایه‌گذاری‌شده
text_with_citations = add_citations(response)
print(text_with_citations)

مدل‌های پشتیبانی‌شده

مدل	پایه‌گذاری با جستجوی گوگل
Gemini 3.1 Pro Preview	✔️
Gemini 3 Pro Preview	✔️
Gemini 3 Flash Preview	✔️
Gemini 2.5 Pro	✔️
Gemini 2.5 Flash	✔️
Gemini 2.5 Flash-Lite	✔️

توجه

مدل‌های قدیمی‌تر از ابزار google_search_retrieval استفاده می‌کنند. برای تمام مدل‌های فعلی، از ابزار google_search همانطور که در مثال‌ها نشان داده شده استفاده کنید.

قیمت‌گذاری

هنگام استفاده از پایه‌گذاری با جستجوی گوگل با مدل‌های Gemini 3، پروژه شما برای هر پرس‌وجوی جستجویی که مدل تصمیم به اجرای آن می‌گیرد صورتحساب می‌شود. اگر مدل تصمیم بگیرد چندین پرس‌وجوی جستجو برای پاسخ به یک پرامپت اجرا کند (مثلا جستجوی "برنده یورو ۲۰۲۴" و "نتیجه فینال اسپانیا - انگلستان یورو ۲۰۲۴" در یک فراخوانی API)، این به عنوان چندین استفاده قابل صورتحساب از ابزار برای آن درخواست محاسبه می‌شود.

برای مدل‌های Gemini 2.5 و قدیمی‌تر، پروژه شما به ازای هر پرامپت که از پایه‌گذاری جستجو استفاده می‌کند صورتحساب می‌شود.

برای اطلاعات دقیق قیمت‌گذاری، صفحه قیمت‌گذاری را ببینید.

تعبیه‌سازی محتوا (Embed Content)

تولید تعبیه‌سازی‌ متن با استفاده از مدل‌های تعبیه‌سازی Gemini از طریق نقطه پایانی SDK بومی Google GenAI.

http

POST /v1beta/models/{model}:embedContent

پارامترها

پارامتر	نوع	الزامی	توضیحات
`model`	string	بله	مدل تعبیه‌سازی Gemini مورد استفاده (مثل `gemini-embedding-001`)

بدنه درخواست

فیلد	نوع	الزامی	توضیحات
`contents`	array	بله	آرایه‌ای از اشیاء محتوا برای تعبیه‌سازی
`embedding_config`	object	خیر	تنظیمات برای تولید تعبیه‌سازی

شیء محتوا

فیلد	نوع	الزامی	توضیحات
`parts`	array	بله	آرایه‌ای از قسمت‌ها حاوی متن برای تعبیه‌سازی

تنظیمات تعبیه‌سازی

فیلد	نوع	توضیحات
`task_type`	string	نوع وظیفه برای بهینه‌سازی (مثل "SEMANTIC_SIMILARITY"، "CLASSIFICATION")
`output_dimensionality`	integer	تعداد ابعاد برای تعبیه‌سازی خروجی (۱۲۸-۳۰۷۲)

مدل‌های پشتیبانی‌شده

نقطه پایانی embedContent از مدل‌های تعبیه‌سازی Gemini زیر پشتیبانی می‌کند:

gemini-embedding-2 (نام مستعار: gemini-embedding-2-preview) - مدل تعبیه‌سازی چندوجهی نسل بعدی با پشتیبانی بومی از متن، تصویر، صدا، ویدیو و PDF از طریق بخش‌های inline_data
gemini-embedding-001 - مدل تعبیه‌سازی پایدار با ویژگی‌های پیشرفته

مثال درخواست

تعبیه‌سازی پایه

bash

curl -X POST 'https://api.avalai.ir/v1beta/models/gemini-embedding-001:embedContent' \
  -H 'Content-Type: application/json' \
  -H 'x-goog-api-key: $AVALAI_API_KEY' \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "معنای زندگی چیست؟"
          }
        ]
      }
    ]
  }'

تعبیه‌سازی پیشرفته با نوع وظیفه

bash

curl -X POST 'https://api.avalai.ir/v1beta/models/gemini-embedding-001:embedContent' \
  -H 'Content-Type: application/json' \
  -H 'x-goog-api-key: $AVALAI_API_KEY' \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "معنای زندگی چیست؟"
          }
        ]
      },
      {
        "parts": [
          {
            "text": "هدف وجود چیست؟"
          }
        ]
      }
    ],
    "embedding_config": {
      "task_type": "SEMANTIC_SIMILARITY",
      "output_dimensionality": 768
    }
  }'

مثال پاسخ

json

{
  "embeddings": [
    {
      "values": [
        0.0023064255,
        -0.009327292,
        -0.0028842222,
        ...
      ]
    }
  ]
}

استفاده با SDK Google GenAI

پایتون

python

from google import genai
from google.genai import types

client = genai.Client(
    api_key="your-avalai-api-key",
    http_options={"api_version": "v1beta", "base_url": "https://api.avalai.ir"},
)

# تعبیه‌سازی پایه
result = client.models.embed_content(
    model="gemini-embedding-001", contents="معنای زندگی چیست؟"
)

print(f"ابعاد تعبیه‌سازی: {len(result.embeddings[0].values)}")

# تعبیه‌سازی پیشرفته با نوع وظیفه و ابعاد سفارشی
result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=["معنای زندگی چیست؟", "هدف وجود چیست؟", "چگونه کیک درست کنم؟"],
    config=types.EmbedContentConfig(
        task_type="SEMANTIC_SIMILARITY", output_dimensionality=768
    ),
)

for i, embedding in enumerate(result.embeddings):
    print(f"تعبیه‌سازی {i}: {len(embedding.values)} بعد")

جاوااسکریپت

javascript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    apiKey: process.env.AVALAI_API_KEY,
    httpOptions: {"apiVersion": "v1beta", "baseUrl": "https://api.avalai.ir"}}
});

// تعبیه‌سازی پایه
const response = await ai.models.embedContent({
    model: "gemini-embedding-001",
    contents: "معنای زندگی چیست؟"
});

console.log(`ابعاد تعبیه‌سازی: ${response.embeddings[0].values.length}`);

// تعبیه‌سازی پیشرفته با نوع وظیفه
const advancedResponse = await ai.models.embedContent({
    model: "gemini-embedding-001",
    contents: [
        "معنای زندگی چیست؟",
        "هدف وجود چیست؟"
    ],
    taskType: "SEMANTIC_SIMILARITY",
    outputDimensionality: 768
});

console.log(`${advancedResponse.embeddings.length} تعبیه‌سازی تولید شد`);

انواع وظایف پشتیبانی‌شده

نوع وظیفه	توضیحات	موارد استفاده
SEMANTIC_SIMILARITY	بهینه‌سازی شده برای اندازه‌گیری شباهت متن	سیستم‌های توصیه، تشخیص تکراری
CLASSIFICATION	بهینه‌سازی شده برای وظایف طبقه‌بندی متن	تحلیل احساسات، تشخیص اسپم
CLUSTERING	بهینه‌سازی شده برای گروه‌بندی متن‌های مشابه	سازماندهی اسناد، تحقیقات بازار
RETRIEVAL_DOCUMENT	بهینه‌سازی شده برای نمایه‌سازی اسناد	سیستم‌های RAG، موتورهای جستجو
RETRIEVAL_QUERY	بهینه‌سازی شده برای پرس‌وجوهای جستجو	برنامه‌های جستجوی سفارشی
CODE_RETRIEVAL_QUERY	بهینه‌سازی شده برای پرس‌وجوهای جستجوی کد	جستجوی کد، جستجوی مستندات
QUESTION_ANSWERING	بهینه‌سازی شده برای سیستم‌های پرسش و پاسخ	چت‌بات‌ها، سیستم‌های FAQ
FACT_VERIFICATION	بهینه‌سازی شده برای بررسی حقایق	سیستم‌های تایید خودکار

ابعاد خروجی

تعبیه‌سازی‌ Gemini از یادگیری نمایش ماتریوشکا (MRL) پشتیبانی می‌کنند که امکان ابعاد خروجی انعطاف‌پذیر را فراهم می‌کند:

۳۰۷۲ بعد: ظرفیت کامل مدل (پیش‌فرض، از قبل نرمال‌سازی شده)
۱۵۳۶ بعد: عملکرد متعادل و کارایی
۷۶۸ بعد: کارآمد با عملکرد خوب
۵۱۲ بعد: فشرده با عملکرد قابل قبول
۲۵۶ بعد: بسیار فشرده
۱۲۸ بعد: حداقل اندازه

مهم

برای ابعاد غیر از ۳۰۷۲، تعبیه‌سازی‌‌ها را برای عملکرد بهینه شباهت معنایی نرمال‌سازی کنید.

فرمت پاسخ

نقطه پایانی embedContent تعبیه‌سازی‌‌ها را در فرمت زیر برمی‌گرداند:

فیلد	نوع	توضیحات
`embeddings`	array	آرایه‌ای از اشیاء تعبیه‌سازی

شیء تعبیه‌سازی

فیلد	نوع	توضیحات
`values`	array	آرایه‌ای از اعداد اعشاری نمایانگر بردار تعبیه‌سازی

تعبیه‌سازی دسته‌ای محتوا (Batch Embed Contents)

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

http

POST /v1beta/models/{model}:batchEmbedContents

پارامترها

پارامتر	نوع	الزامی	توضیحات
`model`	string	بله	مدل تعبیه‌سازی Gemini مورد استفاده (مثل `gemini-embedding-001`)

بدنه درخواست

فیلد	نوع	الزامی	توضیحات
`requests`	array	بله	آرایه‌ای از اشیاء درخواست تعبیه‌سازی

شیء درخواست تعبیه‌سازی

فیلد	نوع	الزامی	توضیحات
`model`	string	بله	مدل مورد استفاده (باید با پارامتر URL مطابقت داشته باشد)
`content`	object	بله	شیء محتوا حاوی متن برای تعبیه‌سازی
`task_type`	string	خیر	نوع وظیفه برای بهینه‌سازی
`output_dimensionality`	integer	خیر	اندازه ابعاد خروجی (۱۲۸-۳۰۷۲)

مثال درخواست

bash

curl -X POST 'https://api.avalai.ir/v1beta/models/gemini-embedding-001:batchEmbedContents' \
  -H 'Content-Type: application/json' \
  -H 'x-goog-api-key: $AVALAI_API_KEY' \
  -d '{
    "requests": [
      {
        "model": "models/gemini-embedding-001",
        "content": {
          "parts": [{
            "text": "معنای زندگی چیست؟"
          }]
        }
      },
      {
        "model": "models/gemini-embedding-001",
        "content": {
          "parts": [{
            "text": "چه مقدار چوب یک چاک‌وود می‌تواند بتکند؟"
          }]
        }
      },
      {
        "model": "models/gemini-embedding-001",
        "content": {
          "parts": [{
            "text": "مغز چگونه کار می‌کند؟"
          }]
        }
      }
    ]
  }'

مثال پاسخ

json

{
  "embeddings": [
    {
      "values": [0.0023064255, -0.009327292, -0.0028842222, ...]
    },
    {
      "values": [0.0034521123, -0.007234567, -0.0021234567, ...]
    },
    {
      "values": [0.0045678901, -0.008765432, -0.0012345678, ...]
    }
  ]
}

استفاده با SDK Google GenAI

پایتون

python

from google import genai
from google.genai import types

client = genai.Client(
    api_key="your-avalai-api-key",
    http_options={"api_version": "v1beta", "base_url": "https://api.avalai.ir"},
)

# تعبیه‌سازی دسته‌ای چندین متن
texts = [
    "معنای زندگی چیست؟",
    "چه مقدار چوب یک چاک‌وود می‌تواند بتکند؟",
    "مغز چگونه کار می‌کند؟",
]

# توجه: از embed_content با لیستی از متن‌ها استفاده کنید
result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=texts,
    config=types.EmbedContentConfig(
        task_type="SEMANTIC_SIMILARITY", output_dimensionality=768
    ),
)

for i, embedding in enumerate(result.embeddings):
    print(f"متن {i}: {len(embedding.values)} بعد")

شمارش توکن‌ها (Count Tokens)

شمارش تعداد توکن‌ها در محتوا قبل از ارسال به مدل. این به شما کمک می‌کند تا استفاده از توکن را درک کرده و در محدودیت‌های مدل باقی بمانید.

http

POST /v1beta/models/{model}:countTokens

پارامترها

پارامتر	نوع	الزامی	توضیحات
`model`	string	بله	مدل Gemini مورد استفاده (مثل `gemini-2.5-flash`)

بدنه درخواست

فیلد	نوع	الزامی	توضیحات
`contents`	array	بله	آرایه‌ای از اشیاء محتوا برای شمارش توکن
`system_instruction`	object	خیر	دستورالعمل سیستمی (در شمارش توکن لحاظ می‌شود)
`tools`	array	خیر	ابزارها/توابع (در شمارش توکن لحاظ می‌شوند)

مثال درخواست

شمارش پایه توکن

bash

curl -X POST 'https://api.avalai.ir/v1beta/models/gemini-2.5-flash:countTokens' \
  -H 'Content-Type: application/json' \
  -H 'x-goog-api-key: $AVALAI_API_KEY' \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "روباه قهوه‌ای سریع از روی سگ تنبل می‌پرد."
          }
        ],
        "role": "user"
      }
    ]
  }'

شمارش توکن با دستورالعمل‌های سیستمی

bash

curl -X POST 'https://api.avalai.ir/v1beta/models/gemini-2.5-flash:countTokens' \
  -H 'Content-Type: application/json' \
  -H 'x-goog-api-key: $AVALAI_API_KEY' \
  -d '{
    "system_instruction": {
      "parts": [
        {
          "text": "شما یک دستیار مفید هستید."
        }
      ]
    },
    "contents": [
      {
        "parts": [
          {
            "text": "معنای زندگی چیست؟"
          }
        ],
        "role": "user"
      }
    ]
  }'

مثال پاسخ

json

{
  "totalTokens": 11
}

استفاده با SDK Google GenAI

پایتون

python

from google import genai
from google.genai import types

client = genai.Client(
    api_key="your-avalai-api-key",
    http_options={"api_version": "v1beta", "base_url": "https://api.avalai.ir"},
)

# شمارش توکن برای متن ساده
prompt = "روباه قهوه‌ای سریع از روی سگ تنبل می‌پرد."
result = client.models.count_tokens(model="gemini-2.5-flash", contents=prompt)
print(f"مجموع توکن‌ها: {result.total_tokens}")

# شمارش توکن برای یک مکالمه
chat_history = [
    types.Content(role="user", parts=[types.Part(text="سلام، اسم من باب است")]),
    types.Content(role="model", parts=[types.Part(text="سلام باب!")]),
    types.Content(
        role="user",
        parts=[types.Part(text="در یک جمله توضیح دهید کامپیوتر چگونه کار می‌کند.")],
    ),
]

result = client.models.count_tokens(model="gemini-2.5-flash", contents=chat_history)
print(f"مجموع توکن‌ها در مکالمه: {result.total_tokens}")

# شمارش توکن با دستورالعمل سیستمی
result = client.models.count_tokens(
    model="gemini-2.5-flash",
    contents=prompt,
    config=types.GenerateContentConfig(system_instruction="شما یک دستیار مفید هستید."),
)
print(f"مجموع توکن‌ها با دستورالعمل سیستمی: {result.total_tokens}")

جاوااسکریپت

javascript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
    apiKey: process.env.AVALAI_API_KEY,
    httpOptions: {apiVersion: "v1beta", baseUrl: "https://api.avalai.ir"}
});

// شمارش توکن برای متن ساده
const result = await ai.models.countTokens({
    model: "gemini-2.5-flash",
    contents: "روباه قهوه‌ای سریع از روی سگ تنبل می‌پرد."
});

console.log(`مجموع توکن‌ها: ${result.totalTokens}`);

// شمارش توکن برای محتوای چندوجهی
const multimodalResult = await ai.models.countTokens({
    model: "gemini-2.5-flash",
    contents: [
        {
            role: "user",
            parts: [
                { text: "درباره این تصویر بگو" },
                { inlineData: { mimeType: "image/jpeg", data: base64ImageData } }
            ]
        }
    ]
});

console.log(`توکن‌های چندوجهی: ${multimodalResult.totalTokens}`);

شمارش توکن برای محتوای چندوجهی

شمارش توکن برای تمام انواع ورودی کار می‌کند:

متن: توکن‌سازی استاندارد (حدود ۴ کاراکتر در هر توکن)
تصاویر:
- Gemini 2.5 به بعد: تصاویر با ابعاد ≤۳۸۴ پیکسل در هر دو بعد = ۲۵۸ توکن
- تصاویر بزرگ‌تر به کاشی‌های ۷۶۸×۷۶۸ پیکسلی تقسیم می‌شوند، هر کاشی = ۲۵۸ توکن
صدا: ۳۲ توکن در ثانیه
ویدیو: ۲۶۳ توکن در ثانیه

مثال: شمارش توکن با تصاویر

python

from google import genai
import PIL.Image

client = genai.Client(
    api_key="your-avalai-api-key",
    http_options={"api_version": "v1beta", "base_url": "https://api.avalai.ir"},
)

image = PIL.Image.open("path/to/image.jpg")

result = client.models.count_tokens(
    model="gemini-2.5-flash", contents=["درباره این تصویر بگو", image]
)

print(f"مجموع توکن‌ها (متن + تصویر): {result.total_tokens}")

Predict (تولید تصویر)

تولید تصاویر با استفاده از مدل‌های Imagen گوگل از طریق API بومی v1beta. این متد از نقطه پایانی :predict برای وظایف تولید تصویر استفاده می‌کند.

http

POST /v1beta/models/{model}:predict

پارامترها

پارامتر	نوع	الزامی	توضیحات
`model`	string	بله	مدل Imagen مورد استفاده (مثلا `imagen-4.0-fast-generate-001`)

مدل‌های پشتیبانی شده

imagen-4.0-generate-001 - تولید تصویر با کیفیت بالا
imagen-4.0-ultra-generate-001 - کیفیت فوق‌العاده بالا (آزمایشی)
imagen-4.0-fast-generate-001 - تولید سریع تصویر
imagen-3.0-generate-002 - مدل نسل قبلی

بدنه درخواست

فیلد	نوع	الزامی	توضیحات
`instances`	array	بله	آرایه‌ای از نمونه‌های درخواست تولید
`parameters`	object	خیر	پارامترهای پیکربندی برای تولید تصویر

شیء Instance

فیلد	نوع	الزامی	توضیحات
`prompt`	string	بله	توصیف متنی تصویر مورد نظر برای تولید

شیء Parameters

فیلد	نوع	پیش‌فرض	توضیحات
`sampleCount`	integer	1	تعداد تصاویر برای تولید (1-8)
`aspectRatio`	string	"1:1"	نسبت ابعاد تصویر ("1:1", "9:16", "16:9", "3:4", "4:3")
`personGeneration`	string	"allow_all"	سیاست تولید افراد ("allow_all", "allow_adult")
`safetyFilterLevel`	string	"block_some"	قدرت فیلتر ایمنی ("block_most", "block_some", "block_few")
`negativePrompt`	string	null	آنچه باید در تصویر تولید شده اجتناب شود

مثال درخواست

bash

curl -X POST \
  "https://api.avalai.ir/v1beta/models/imagen-4.0-fast-generate-001:predict" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instances": [
      {
        "prompt": "یک باغ ژاپنی آرام با استخر ماهی کوی، شکوفه‌های گیلاس و یک پل چوبی سنتی"
      }
    ],
    "parameters": {
      "sampleCount": 1,
      "aspectRatio": "16:9"
    }
  }'

مثال پاسخ

json

{
  "predictions": [
    {
      "bytesBase64Encoded": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
      "mimeType": "image/png"
    }
  ],
  "metadata": {
    "tokenMetadata": {
      "outputImageCount": {
        "imagen-4.0-fast-generate-001": 1
      }
    }
  }
}

فیلدهای پاسخ

فیلد	نوع	توضیحات
`predictions`	array	آرایه‌ای از پیش‌بینی‌های تصویر تولید شده
`bytesBase64Encoded`	string	داده‌های تصویر کدگذاری شده base64
`mimeType`	string	نوع MIME تصویر (معمولا "image/png")
`metadata`	object	متادیتای استفاده شامل تعداد توکن‌ها

رمزگشایی تصاویر

برای ذخیره تصویر تولید شده، رشته base64 را رمزگشایی کنید:

python

import base64

# رمزگشایی و ذخیره تصویر
image_data = base64.b64decode(response["predictions"][0]["bytesBase64Encoded"])
with open("generated_image.png", "wb") as f:
    f.write(image_data)

بهترین شیوه‌ها

مهندسی پرامپت: از پرامپت‌های دقیق و مشخص برای نتایج بهتر استفاده کنید
نسبت ابعاد: نسبت ابعاد مناسب را برای مورد استفاده خود انتخاب کنید
تعداد نمونه: چندین تصویر (2-4) تولید کنید تا نتایج متنوع دریافت کنید
فیلترهای ایمنی: فیلترهای ایمنی را بر اساس سیاست محتوای خود تنظیم کنید
پرامپت‌های منفی: از پرامپت‌های منفی برای اجتناب از عناصر ناخواسته استفاده کنید

برای مثال‌های دقیق و راهنمای مهندسی پرامپت، مراجعه کنید به:

مدیریت خطا

API v1beta کدهای وضعیت HTTP استاندارد را برمی‌گرداند:

200 - موفقیت
400 - درخواست نامعتبر (پارامترهای نامعتبر)
401 - غیرمجاز (کلید API نامعتبر)
429 - درخواست‌های زیاد (محدودیت نرخ فراتر رفته)
500 - خطای داخلی سرور

فرمت پاسخ خطا

json

{
  "error": {
    "code": 400,
    "message": "فرمت درخواست نامعتبر",
    "status": "INVALID_ARGUMENT"
  }
}

محدودیت‌های نرخ

محدودیت‌های نرخ برای API v1beta از همان ساختار سایر نقاط پایانی AvalAI پیروی می‌کند. برای جزئیات مستندات محدودیت‌های نرخ را ببینید.

محدودیت‌ها

فقط مدل‌های گوگل: API v1beta منحصرا از مدل‌های گوگل (Gemini و Imagen) پشتیبانی می‌کند. سایر سرویس‌های گوگل در دسترس نیستند.
URL پایه: هنگام پیکربندی SDK Google GenAI باید از https://api.avalai.ir (بدون /v1) استفاده کرد.
فرمت تصویر: تصاویر باید به صورت داده‌های کدگذاری شده base64 ارائه شوند، نه به عنوان URL های خارجی.

مرجع API v1beta SDK Google GenAI ​

URL پایه ​

احراز هویت ​

روش ۱: Bearer Token (توصیه شده) ​

روش ۲: هدر بومی گوگل ​

مدل‌های پشتیبانی شده ​

مدل‌های Gemini (متن، بینایی، صوتی) ​

مدل‌های Imagen (تولید تصویر) ​

نقاط پایانی ​

تولید محتوا ​

پارامترها ​

بدنه درخواست ​

شی محتوا ​

شی دستورالعمل سیستمی ​

پیکربندی تولید ​

پیکربندی گفتار (speechConfig) ​

پیکربندی صدای تک گوینده (voiceConfig) ​

پیکربندی صدای از پیش ساخته شده (prebuiltVoiceConfig) ​

پیکربندی صدای چند گوینده (multiSpeakerVoiceConfig) ​

پیکربندی صدای گوینده (speakerVoiceConfig) ​

پیکربندی تفکر (مدل‌های Gemini) ​

نمونه درخواست ​

نمونه با دستورالعمل‌های سیستمی ​

نمونه پاسخ ​

تولید محتوای جریانی ​

نمونه درخواست ​

نمونه پاسخ جریانی ​

استفاده با SDK Google GenAI ​

Python ​

جریان با Python ​

پشتیبانی چندوجهی ​

نمونه ورودی تصویر ​

پایه‌گذاری با جستجوی گوگل (Grounding with Google Search) ​

مزایای کلیدی ​

نمونه درخواست ​

استفاده با SDK Google GenAI ​

Python ​

JavaScript ​

نحوه کار پایه‌گذاری ​

درک پاسخ پایه‌گذاری ​

نسبت‌دهی منابع با استنادات درون‌خطی ​

مدل‌های پشتیبانی‌شده ​

قیمت‌گذاری ​

تعبیه‌سازی محتوا (Embed Content) ​

پارامترها ​

بدنه درخواست ​

شیء محتوا ​

تنظیمات تعبیه‌سازی ​

مدل‌های پشتیبانی‌شده ​

مثال درخواست ​

تعبیه‌سازی پایه ​

تعبیه‌سازی پیشرفته با نوع وظیفه ​

مثال پاسخ ​

استفاده با SDK Google GenAI ​

پایتون ​

جاوااسکریپت ​

انواع وظایف پشتیبانی‌شده ​

ابعاد خروجی ​

فرمت پاسخ ​

شیء تعبیه‌سازی ​

تعبیه‌سازی دسته‌ای محتوا (Batch Embed Contents) ​

پارامترها ​

بدنه درخواست ​

شیء درخواست تعبیه‌سازی ​

مثال درخواست ​

مثال پاسخ ​

استفاده با SDK Google GenAI ​

پایتون ​

شمارش توکن‌ها (Count Tokens) ​

پارامترها ​

بدنه درخواست ​

مثال درخواست ​

شمارش پایه توکن ​

شمارش توکن با دستورالعمل‌های سیستمی ​

مثال پاسخ ​

استفاده با SDK Google GenAI ​

پایتون ​

جاوااسکریپت ​

شمارش توکن برای محتوای چندوجهی ​

مثال: شمارش توکن با تصاویر ​

مرجع API v1beta SDK Google GenAI

URL پایه

احراز هویت

روش ۱: Bearer Token (توصیه شده)

روش ۲: هدر بومی گوگل

مدل‌های پشتیبانی شده

مدل‌های Gemini (متن، بینایی، صوتی)

مدل‌های Imagen (تولید تصویر)

نقاط پایانی

تولید محتوا

پارامترها

بدنه درخواست

شی محتوا

شی دستورالعمل سیستمی

پیکربندی تولید

پیکربندی گفتار (speechConfig)

پیکربندی صدای تک گوینده (voiceConfig)

پیکربندی صدای از پیش ساخته شده (prebuiltVoiceConfig)

پیکربندی صدای چند گوینده (multiSpeakerVoiceConfig)

پیکربندی صدای گوینده (speakerVoiceConfig)

پیکربندی تفکر (مدل‌های Gemini)

نمونه درخواست

نمونه با دستورالعمل‌های سیستمی

نمونه پاسخ

تولید محتوای جریانی

نمونه درخواست

نمونه پاسخ جریانی

استفاده با SDK Google GenAI

Python

جریان با Python

پشتیبانی چندوجهی

نمونه ورودی تصویر

پایه‌گذاری با جستجوی گوگل (Grounding with Google Search)

مزایای کلیدی

نمونه درخواست

استفاده با SDK Google GenAI

Python

JavaScript

نحوه کار پایه‌گذاری

درک پاسخ پایه‌گذاری

نسبت‌دهی منابع با استنادات درون‌خطی

مدل‌های پشتیبانی‌شده

قیمت‌گذاری

تعبیه‌سازی محتوا (Embed Content)

پارامترها

بدنه درخواست

شیء محتوا

تنظیمات تعبیه‌سازی

مدل‌های پشتیبانی‌شده

مثال درخواست

تعبیه‌سازی پایه

تعبیه‌سازی پیشرفته با نوع وظیفه

مثال پاسخ

استفاده با SDK Google GenAI

پایتون

جاوااسکریپت

انواع وظایف پشتیبانی‌شده

ابعاد خروجی

فرمت پاسخ

شیء تعبیه‌سازی

تعبیه‌سازی دسته‌ای محتوا (Batch Embed Contents)

پارامترها

بدنه درخواست

شیء درخواست تعبیه‌سازی

مثال درخواست

مثال پاسخ

استفاده با SDK Google GenAI

پایتون

شمارش توکن‌ها (Count Tokens)

پارامترها

بدنه درخواست

مثال درخواست

شمارش پایه توکن

شمارش توکن با دستورالعمل‌های سیستمی

مثال پاسخ

استفاده با SDK Google GenAI

پایتون

جاوااسکریپت

شمارش توکن برای محتوای چندوجهی

مثال: شمارش توکن با تصاویر