پشتیبانی از فایل (PDF و متن)
فرستادن یک سند یا فایل متنی همراه با پیام، تا مدل محتوای آن را بخواند
مستندات
چه چیزی روی چه مدلی کار میکند
این قابلیت در حال انتشار است. اگر همین حالا فایلی بفرستید ممکن است مدل بگوید فایلی نمیبیند، بدون آنکه خطایی برگردد. تا کامل شدن انتشار، محتوای فایل را مستقیم داخل متن پیام بگذارید.
پشتیبانی از پیوست به ارائهدهندهٔ بالادست بستگی دارد، نه به تکتک مدلها. ستون آخر همهجا «بله» است و این یک استثنا نیست:
| ارائهدهنده | نمونهٔ مدل | تصویر | فایل متنی | |
|---|---|---|---|---|
| Anthropic | claude-* | بله | بله | بله |
| OpenAI | gpt-* | بله | بله | بله |
| OpenRouter | gemini-*, glm-* | بله | بله | بله |
| DeepSeek | deepseek-* | خیر | خیر | بله |
| محلی / هیبانا | gpt-oss, qwen-3 | خیر | خیر | بله |
اگر مدلی PDF نمیپذیرد، همان محتوا را به شکل متنی بفرستید. فایل متنی هرگز بهعنوان پیوست به ارائهدهنده نمیرسد: درگاه آن را رمزگشایی میکند و محتوایش را مثل متن عادی داخل درخواست میگذارد. برای همین روی هر مدلی کار میکند، حتی مدلهایی که PDF را رد میکنند.
دو نتیجه که بهتر است بدانید: کلمات فایل بخشی از prompt میشوند (فایلی که دستور داخلش باشد، بهعنوان دستور خوانده میشود)، و مثل توکن ورودی عادی حساب میشود.
این صفحه دربارهٔ فرستادن فایل به مدل است. برای فرستادن عکس به ورودی تصویر بروید، و اگر میخواهید مدل تصویر بسازد، تولید تصویر با AI جای درست است.
فرستادن فایل متنی
فایل را بخوانید، Base64 کنید، و با پیشوند data:text/markdown;base64, در یک بخش file بگذارید. این نمونهها روی gpt-oss اجرا میشوند — مدلی که PDF نمیپذیرد — و همین نشان میدهد فایل متنی روی هر مدلی کار میکند.
NOTES=$(base64 -w0 notes.md) curl https://api-ai.hibanacloud.ir/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-oss", "messages": [{ "role": "user", "content": [ {"type": "text", "text": "شمارهٔ ثبت در این فایل چند است؟ فقط عدد را بنویس."}, { "type": "file", "file": { "filename": "notes.md", "file_data": "data:text/markdown;base64,'"$NOTES"'" } } ] }], "max_completion_tokens": 1000 }'پسوندهای پذیرفتهشده: .txt .md .csv .tsv .json .jsonl .xml .yaml .yml .log .ini .toml .conf .py .js .ts .tsx .cs .java .go .rs .rb .php .c .cpp .h .sql .sh .ps1 و فایلهای کد مشابه. .html عمداً پذیرفته نمیشود.
فایل متنی باید UTF-8 باشد، یا encoding خودش را اعلام کند. اینجا هیچ حدسی دربارهٔ charset زده نمیشود، چون یک فایل windows-1256 که بهاشتباه UTF-8 خوانده شود به هم میریزد و کاربر فقط به شکل «جواب اشتباه» متوجهش میشود. برای یک فایل فارسی قدیمی: data:text/plain;charset=windows-1256;base64,…
فرستادن PDF
همان شکل، با data:application/pdf;base64,. این نمونهها روی یک مدل Anthropic اجرا میشوند، چون PDF فقط روی ارائهدهندههای جدول بالا کار میکند.
# سند باید PDF باشد و به شکل data URI فرستاده شود.PDF=$(base64 -w0 document.pdf) curl https://api-ai.hibanacloud.ir/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-5", "messages": [{ "role": "user", "content": [ {"type": "text", "text": "این گواهی مربوط به کدام شرکت است؟ فقط نام شرکت را بنویس."}, { "type": "file", "file": { "filename": "document.pdf", "file_data": "data:application/pdf;base64,'"$PDF"'" } } ] }], "max_completion_tokens": 1000 }'هر نمونه پیش از پاسخ prompt_tokens را چاپ میکند؛ چرایش در وقتی جواب خالی است آمده. docx و xlsx و pptx پشتیبانی نمیشوند و قرار هم نیست بشوند — هیچکدام از ارائهدهندهها آنها را نمیپذیرند. فایل را به PDF یا متن تبدیل کنید.
ساختار content
در یک درخواست معمولی، content یک رشته است. برای فرستادن پیوست، به آرایهای از «بخش»ها تبدیل میشود — همان تغییری که ورودی تصویر هم لازم دارد:
| نوع بخش | فیلد داده | توضیح |
|---|---|---|
| type: "text" | text | متن پیام کاربر. همان چیزی که در حالت بدون پیوست یک رشتهٔ ساده بود. |
| type: "file" | file.filename | نام فایل، مثل «notes.md». نوع فایل از روی همین پسوند تشخیص داده میشود اگر media type اعلام نشود. |
| type: "file" | file.file_data | خود فایل: یک data URI با Base64 (پیشنهادی) یا یک نشانی https که درگاه خودش آن را دانلود میکند. |
Base64 را توصیه میکنیم: فایل داخل خود درخواست سفر میکند، پس هیچ چیزی هنگام گرفتنش شکست نمیخورد. نشانی هم کار میکند — درگاه آن را برای شما دانلود میکند — ولی باید عمومی باشد و یک مرحلهٔ دانلود به هر درخواست اضافه میکند. نام file_url هم بهعنوان معادل پذیرفته میشود:
{ "type": "file", "file": { "filename": "document.pdf", "file_data": "https://example.com/document.pdf" }}بقیهٔ درخواست تغییری نمیکند: همان model، همان messages، همان پارامترهای Chat Completions. با stream: true هم کار میکند؛ به استریم پاسخ نگاه کنید.
محدودیتها
| محدودیت | توضیح |
|---|---|
| تصویر و PDF | ۸ مگابایت برای هر پیوست. این سقف هم برای فایلی که با نشانی دانلود میشود اعمال میشود و هم برای Base64 داخل خود درخواست؛ عبور از آن به file_too_large برای PDF و image_too_large برای تصویر میانجامد. |
| فایل متنی | ۲۵۶ کیلوبایت برای هر فایل، و ۵۱۲ کیلوبایت متن در کل یک درخواست. |
| نوع از روی بایتها | نوع فایل از محتوای واقعی تشخیص داده میشود، نه از چیزی که درخواست ادعا میکند. یک PNG با برچسب application/pdf رد میشود، و همان PNG با برچسب text/plain هم بهعنوان فایل دودویی رد میشود. |
| ۱۰ نشانی | حداکثر ۱۰ نشانی متمایز در هر درخواست. پیوستهای Base64 مشمول این سقف نیستند. |
| نشانی عمومی | نشانی باید از بیرون در دسترس باشد. آدرسهای داخلی و خصوصی عمداً رد میشوند. |
| file_id پشتیبانی نمیشود | فایلی که با client.files.create() در حساب OpenAI ذخیره شده باشد برای این درگاه قابل خواندن نیست. بهجایش file_data را مستقیم بفرستید. |
سقف ۸ مگابایت روی فایل خام است، نه روی رشتهٔ Base64. کدگذاری Base64 حدود ۳۳٪ به حجم اضافه میکند، پس یک فایل ۸ مگابایتی در بدنهٔ JSON چیزی نزدیک ۱۰٫۷ مگابایت میشود — اگر بدنهٔ درخواست را اندازه میگیرید، این عدد را ببینید نه حجم فایل روی دیسک.
هزینه را حجم فایل تعیین نمیکند. متن حدوداً یک توکن به ازای هر چهار بایت حساب میشود، پس یک فایل ۲۵۶ کیلوبایتی چیزی نزدیک ۶۴٬۰۰۰ توکن ورودی است. PDF گرانتر و بسیار متغیرتر است: در اندازهگیریها یک گواهی یکصفحهای ۱٬۶۸۲ توکن و یک سند ۹۸ صفحهای ۲۲۸٬۸۵۳ توکن مصرف کرد. قاعدهٔ سرانگشتی ۱٬۵۰۰ تا ۳٬۰۰۰ توکن برای هر صفحه است، نه حجم فایل — آن دو نمونه به ازای هر بایت ۲۳ برابر با هم فرق دارند. جزئیات در قیمتگذاری.
روی endpoint دیگر
روی /v1/responses همین قابلیت هست، فقط نام بخش فرق میکند و فیلدها بهجای تودرتو، مستقیم کنار هم میآیند:
{ "type": "input_file", "filename": "document.pdf", "file_data": "data:application/pdf;base64,JVBERi0xLjcK..."}وقتی جواب خالی است
مدلهای استدلالی به بودجهٔ صریح نیاز دارند. اگر روی gpt-5-nano و همخانوادههایش reasoning_effort: "low" نگذارید یا max_tokens را بزرگ نکنید، تمام بودجه صرف استدلال میشود و پاسخ با محتوای خالی روی HTTP 200 برمیگردد. خراب به نظر میرسد و خراب نیست. این مخصوص پیوست نیست، ولی پیوست خیلی محتملترش میکند.
پیش از هر چیز usage.prompt_tokens را بخوانید. یک PDF یکصفحهای این عدد را از ۱۰۰۰ بالاتر میبرد؛ اگر نزدیک ۵۰ ماند، پیوست اصلاً به مدل نرسیده است. این نشانهٔ بهمراتب بهتری است از هر چیزی که مدل در متن پاسخ میگوید — مدلی که فایل را ندیده معمولاً مؤدبانه میگوید فایلی نمیبیند، ولی گاهی هم حدس میزند.
فهرست کامل خطاهای پیوست و معنی هرکدام در مدیریت خطاها آمده است. اگر کد خطا ندارید ولی نتیجه درست نیست، از حل مشکلات شروع کنید.