مستند رسمی کتابخانه BGPT Agent

معرفی

BGPT Agent یک کتابخانه قدرتمند پایتون برای ارتباط با مدل‌های مختلف هوش مصنوعی است. این کتابخانه امکان گفتگوی متنی، تولید تصویر، ساخت ویدئو، تبدیل صوت به متن، تحلیل تصویر و مدیریت هزینه را با یک API ساده فراهم می‌کند.

ویژگی‌های کلیدی

• پشتیبانی از مدل‌های متنی پیشرفته
• تولید تصویر با کیفیت بالا
• ساخت ویدئو با مدل‌های پیشرفته
• تحلیل تصویر با مدل‌های چندوجهی
• تبدیل صوت به متن
• محاسبه دقیق هزینه کم شده از حساب
• مدیریت موجودی و تخمین هزینه قبل از درخواست
• پشتیبانی از زبان فارسی

نصب

pip install bgpt-agent

شروع سریع

ساخت کلید از اینجا

from bgpt_agent import BGPTAgent

agent = BGPTAgent(
    api_key="your-api-key-here",
    verbose=True,
    language="fa"
)

response = agent.chat(
    model_code="txt-00001",
    messages=[{"role": "user", "content": "سلام! چطوری؟"}]
)

print(response['choices'][0]['message']['content'])
print(f"هزینه این درخواست: {response['billing']['cost']:.6f} دلار")

__init__(api_key, verbose=False, language="en")

ساخت یک نمونه از کلاینت.

chat(model_code, messages, temperature=0.7, max_tokens=None, ...)

ارسال یک مکالمه به مدل متنی و دریافت پاسخ.

response = agent.chat(
    model_code="txt-00001",
    messages=[
        {"role": "system", "content": "تو یک دستیار مفید هستی"},
        {"role": "user", "content": "هوش مصنوعی چیست؟"}
    ],
    temperature=0.7,
    max_tokens=500
)

print(f"هزینه: {response['billing']['cost']:.6f} دلار")
print(f"موجودی باقیمانده: {response['billing']['remaining_balance']:.4f} دلار")

generate_image(model_code, prompt, negative_prompt="", size="1024x1024", num_images=1, ...)

تولید تصویر بر اساس توضیحات متنی.

result = agent.generate_image(
    model_code="img-00002",
    prompt="کوه دماوند در طلوع خورشید",
    negative_prompt="متن، واترمارک",
    size="1792x1024",
    num_images=2,
    quality="hd",
    save_to="./output.png"
)

print(f"هزینه ساخت تصویر: {result['billing']['cost']:.4f} دلار")

analyze_image(model_code, prompt, image_path=None, image_url=None, detail="auto", ...)

تحلیل یک تصویر با مدل بینایی.

result = agent.analyze_image(
    model_code="txt-00001",
    prompt="این تصویر چه چیزی را نشان می‌دهد؟",
    image_path="./photo.jpg",
    detail="high",
    temperature=0.5
)

print(f"تحلیل کامل شد. هزینه: {result['billing']['cost']:.6f} دلار")

generate_video(model_code, prompt, duration=5, resolution="1080p", style="cinematic", ...)

ساخت ویدئو با هوش مصنوعی.

result = agent.generate_video(
    model_code="vid-00001",
    prompt="موج‌های اقیانوس در غروب آفتاب",
    duration=8,
    resolution="1080p",
    fps=24,
    wait_for_completion=True
)

if result.get('success'):
    print(f"ویدئو ساخته شد. هزینه: {result['billing']['cost']:.4f} دلار")
    print(f"آدرس ویدئو: {result['video']['url']}")

transcribe_audio(model_code, audio_path, language=None, response_format="json")

تبدیل فایل صوتی به متن.

result = agent.transcribe_audio(
    model_code="aud-00001",
    audio_path="./speech.mp3",
    language="fa",
    response_format="text"
)

print(f"متن تبدیل شده: {result['text']}")
print(f"هزینه تبدیل: {result['billing']['cost']:.6f} دلار")

get_balance()

دریافت اطلاعات کامل حساب کاربری.

balance = agent.get_balance()
print(f"موجودی فعلی: {balance['balance']:.4f} دلار")
print(f"کل هزینه‌های شما تا امروز: {balance['total_spent']:.4f} دلار")
print(f"تعداد کل درخواست‌ها: {balance['total_requests']}")

estimate_cost(model_code, message, estimated_response_tokens=300)

تخمین هزینه قبل از ارسال درخواست واقعی.

estimate = agent.estimate_cost(
    model_code="txt-00001",
    message="یک مقاله ۱۰۰۰ کلمه‌ای درباره هوش مصنوعی بنویس",
    estimated_response_tokens=2000
)

print("تخمین هزینه:")
print(f"  - مدل: {estimate['model_code']}")
print(f"  - هزینه تقریبی: {estimate['estimated_cost']:.6f} دلار")

list_available_models(model_type=None)

دریافت لیست مدل‌های موجود.

all_models = agent.list_available_models()
image_models = agent.list_available_models(model_type="image")
text_models = agent.list_available_models(model_type="text")

مقادیر model_type: "text", "image", "video", "audio"

کدهای مدل‌های پیش‌فرض

مدیریت خطاها

همه توابع در صورت بروز خطا یک دیکشنری با کلید "error" برمی‌گردانند:

response = agent.chat(...)
if 'error' in response:
    print(f"خطا: {response['error']}")
    print(f"کد خطا: {response.get('error_code')}")
else:
    pass

مثال کامل: ربات پشتیبانی فارسی

from bgpt_agent import BGPTAgent

agent = BGPTAgent(api_key="YOUR_KEY", language="fa")

def support_bot(user_question):
    estimate = agent.estimate_cost("txt-00001", user_question)
    print(f"هزینه تقریبی: {estimate['estimated_cost']:.6f} دلار")
    
    balance = agent.get_balance()
    if balance['balance'] < estimate['estimated_cost']:
        return "متأسفانه موجودی حساب کافی نیست."
    
    response = agent.chat(
        model_code="txt-00001",
        messages=[
            {"role": "system", "content": "تو پشتیبان فروشگاه هستی، مودب و حرفه‌ای پاسخ بده."},
            {"role": "user", "content": user_question}
        ],
        temperature=0.3,
        max_tokens=500
    )
    
    if 'choices' in response:
        print(f"هزینه نهایی: {response['billing']['cost']:.6f} دلار")
        return response['choices'][0]['message']['content']
    else:
        return f"خطا: {response.get('error', 'مشکل ناشناخته')}"

print(support_bot("سفارش من دیر رسیده، چه کار کنم؟"))

نکات بهینه‌سازی هزینه

پشتیبانی و ارتباط

• وبسایت: bgpt.ir
• ایمیل پشتیبانی: support@bgpt.ir

مجوز

این کتابخانه تحت مجوز MIT منتشر شده است.

تاریخ آخرین بروزرسانی: ژوئن ۲۰۲۶