تصاویر و فایلها
تصاویر را همراه پیام بفرستید: کدام مدلها آنها را میپذیرند، شکلهای پذیرفتهشده و محدودیتهایشان.
POST https://api.shannon-ai.com/v1/chat/completions
تصویر داخل پیام کاربر، بهعنوان یک بخش از content آن، فرستاده میشود. نمونه یک فایل محلی را میخواند و آن را بهصورت data URL میفرستد.
import base64
from openai import OpenAI
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")
with open("photo.jpg", "rb") as f:
image = base64.b64encode(f.read()).decode()
response = client.chat.completions.create(
model="shannon-3",
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "What is in this picture?"},
{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64," + image}},
],
}],
)
print(response.choices[0].message.content) import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1" });
const image = fs.readFileSync("photo.jpg").toString("base64");
const response = await client.chat.completions.create({
model: "shannon-3",
messages: [{
role: "user",
content: [
{ type: "text", text: "What is in this picture?" },
{ type: "image_url", image_url: { url: "data:image/jpeg;base64," + image } },
],
}],
});
console.log(response.choices[0].message.content); # Linux: base64 -w0 photo.jpg macOS: base64 -i photo.jpg
IMAGE=$(base64 -w0 photo.jpg)
curl https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d @- <<EOF
{
"model": "shannon-3",
"messages": [{
"role": "user",
"content": [
{"type": "text", "text": "What is in this picture?"},
{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,${IMAGE}"}}
]
}]
}
EOF {
"id": "chatcmpl-8d1f3a5c7e9b4d2f6a8c0e2b4d6f8a1c",
"object": "chat.completion",
"created": 1791590400,
"model": "shannon-3",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "A grey cat asleep on a windowsill, with a potted fern beside it.",
"reasoning_content": null
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 286,
"completion_tokens": 19,
"total_tokens": 305
}
} کدام مدلها تصویر میپذیرند
| مدلها | میخواند |
|---|---|
shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro | تصاویر، و اسناد: PDF، Word، PowerPoint، Excel و فایلهای متن ساده. |
shannon-1.6-lite, shannon-1.6-pro | تصاویر. |
shannon-2-lite, shannon-2-pro | تصاویر، در درخواستهایی که tools یا response_format هم میفرستند. |
Kimi-K3-3BIT-REAP, MiniMax-M3-3BIT-REAP, Kimi-K2.6-W4A16-AUTOROUND-REAP, inkling-W4A16-AUTOROUND-REAP, MiMo-V2.5-W8A16 | تصاویر. |
DeepSeek-V4-Pro-0813-3BIT-REAP, GLM-5.2-3BIT-REAP, Nemotron3Ultra-3BIT-REAP, DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP, Laguna-S-2.1-W4A16-AUTOROUND-REAP, MiMo-V2.5-Pro-W8A16, Hy3-W8A16 | متن. درخواست دارای تصویر با وضعیت 400 پاسخ داده میشود. |
shannon-coder-1 | متن. |
GET /v1/models ورودی تصویر را برای هر شناسه بهصورت capabilities.vision گزارش میکند. مدلها و قیمتها
- مدلهای Shannon فایلهای آخرین پیام کاربر را میخوانند. تصویر را در پیامی بگذارید که درباره آن میپرسد.
- خانواده Shannon 3 همچنین چند تصویر و سند از پیامهای قبلی کاربر را، اگر درونخطی فرستاده شده باشند، در نظر نگه میدارد و در هر درخواست حداکثری مشخص از تصاویر را، از اولین تصویر به بعد، میخواند.
- مدلهای open-weight میزبانیشده تصاویر همه پیامهای گفتگو را میخوانند.
شکلهای پذیرفتهشده
فایل به یکی از دو روش فرستاده میشود: داخل درخواست بهصورت base64، یا بهصورت آدرسی که API آن را دریافت میکند. هر فایل همراه درخواست حرکت میکند؛ API endpoint آپلود ندارد.
| Endpoint | در درخواست (base64) | با آدرس |
|---|---|---|
/v1/chat/completions | {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,…"}} | {"type": "image_url", "image_url": {"url": "https://…"}} |
/v1/responses | {"type": "input_image", "image_url": "data:image/jpeg;base64,…"} | {"type": "input_image", "image_url": "https://…"} |
/v1/messages | {"type": "image", "source": {"type": "base64", "media_type": "image/jpeg", "data": "…"}} | {"type": "image", "source": {"type": "url", "url": "https://…"}} |
همان پیام کاربر در هر فرمت:
{
"role": "user",
"content": [
{"type": "text", "text": "What is in this picture?"},
{
"type": "image_url",
"image_url": {
"url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD…"
}
}
]
} {
"role": "user",
"content": [
{"type": "input_text", "text": "What is in this picture?"},
{
"type": "input_image",
"image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD…"
}
]
} {
"role": "user",
"content": [
{"type": "text", "text": "What is in this picture?"},
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRgABAQAAAQABAAD…"
}
}
]
} - data URL شکل
data:<media type>;base64,<data>دارد. بخش;base64الزامی است. - روی
/v1/chat/completionsو/v1/responses،image_urlمیتواند خود رشته یا شیء{"url": "…"}باشد. - نوع فایل از data URL یا از
media_typeگرفته میشود. بدون آن، تصویر بهصورتimage/pngخوانده میشود. - فایلهای درونخطی در اندازه بدنه درخواست شمرده میشوند که میتواند تا 32 MiB باشد.
- برای سازگاری پذیرفته میشود:
image_url.detail.
محدودیتهای فایلهای راه دور
وقتی آدرس میفرستید، API پیش از اجرای مدل فایل را در این محدودیتها دریافت میکند:
| محدودیت | قاعده |
|---|---|
| اندازه | تا 8 MiB برای هر فایل. |
| زمان | 20 ثانیه برای پاسخ دادن. |
| تغییر مسیرها | حداکثر 5. |
| آدرس | http:// یا https://، بدون نام کاربری یا گذرواژه در آدرس، روی هاستی با آدرس عمومی. |
| پاسخ هاست | وضعیتی در محدوده 200 و بدنهای که خالی نباشد. نوع فایل از Content-Type خوانده میشود. |
| درخواستشده با | User-Agent: ShannonBot/1.0 (+https://shannon-ai.com) |
تصاویر چگونه بر حسب توکن شمرده میشوند
در مدلهای open-weight میزبانیشده، یک تصویر به ازای هر تکه 28 × 28 پیکسلی یک توکن حساب میشود: عرض تقسیم بر 28 و گرد به بالا، ضربدر ارتفاع تقسیم بر 28 و گرد به بالا. نتیجه بخشی از usage.prompt_tokens است و بهعنوان ورودی محاسبه میشود.
- 1024 × 1024
- 1,369 توکن
- 1920 × 1080
- 2,691 توکن
- 512 × 512
- 361 توکن
- تصویر راه دور ابتدا دریافت میشود، پس اندازه واقعی آن شمرده میشود.
- تصویری که اندازهاش خوانده نشود 1,024 توکن حساب میشود.
- endpointهای شمارش برای data URLها از همین قاعده استفاده میکنند. آدرس راه دور را دریافت نمیکنند و آن را 1,024 توکن میشمارند. شمارش توکن
- برای مدل Shannon، هزینه درخواست دارای تصویر را از
usageدر پاسخ بخوانید.
اسناد و فایلهای دیگر
خانواده Shannon 3 (shannon-3، shannon-3-pro، shannon-3.1، shannon-3.1-pro) اسناد را هم میخواند. متن سند استخراج میشود و همراه پیام شما به مدل داده میشود.
| سند | نوع رسانه |
|---|---|
application/pdf | |
| Word | application/vnd.openxmlformats-officedocument.wordprocessingml.document |
| PowerPoint | application/vnd.openxmlformats-officedocument.presentationml.presentation |
| Excel | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
سند بخشی از پیام کاربر است، مثل تصویر:
| Endpoint | در درخواست (base64) | با آدرس |
|---|---|---|
/v1/chat/completions, /v1/messages | {"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} | {"type": "document", "source": {"type": "url", "url": "https://…"}} |
/v1/responses | {"type": "input_file", "file_data": "data:application/pdf;base64,…"} | {"type": "input_file", "file_url": "https://…"} |
{
"model": "shannon-3",
"messages": [
{
"role": "user",
"content": [
{
"type": "document",
"source": {
"type": "base64",
"media_type": "application/pdf",
"data": "JVBERi0xLjcKJeLjz9MK…"
}
},
{"type": "text", "text": "Summarise this report in five points."}
]
}
]
} {
"model": "shannon-3",
"input": [
{
"role": "user",
"content": [
{
"type": "input_file",
"file_data": "data:application/pdf;base64,JVBERi0xLjcKJeLjz9MK…"
},
{
"type": "input_text",
"text": "Summarise this report in five points."
}
]
}
]
} {
"model": "shannon-3",
"messages": [
{
"role": "user",
"content": [
{
"type": "document",
"source": {
"type": "base64",
"media_type": "application/pdf",
"data": "JVBERi0xLjcKJeLjz9MK…"
}
},
{"type": "text", "text": "Summarise this report in five points."}
]
}
]
} - نوع رسانه واقعی فایل را بدهید. بدون آن، سند بهصورت
application/pdfخوانده میشود. - فایل متن ساده، مانند CSV، بهصورت متن خوانده و به همان شکل ضمیمه میشود.
- وقتی سندی خوانده نشود یا فایل از نوع دیگری باشد، این موضوع به مدل گفته میشود و مدل میتواند در پاسخ آن را بگوید. وضعیت همچنان
200است. - در هر مدل دیگر، بخش سند از آنچه مدل میخواند حذف میشود و درخواست از بقیه آن پاسخ داده میشود.
- سندی که با آدرس فرستاده شود تحت محدودیتهای فایلهای راه دور در بالا دریافت میشود.
خطاها
| وضعیت | نوع | پیام | زمان |
|---|---|---|---|
400 | invalid_request_error | <id> does not accept image input | یک تصویر به مدل open-weight میزبانیشدهای فرستاده شد که فقط متن میپذیرد. چیزی از موجودی شما کم نمیشود. |
400 | invalid_request_error | audio and video input are not supported by any hosted model | یک بخش صوتی یا تصویری به مدل open-weight میزبانیشده فرستاده شد. |
413 | invalid_request_error | Failed to buffer the request body: … | بدنه درخواست، همراه فایلهای درونخطیاش، از 32 MiB بزرگتر است. خطا code: "request_too_large" را دارد. |
مدل Shannon با هر فایلی که درخواست داشته باشد با وضعیت 200 پاسخ میدهد: بخشی که نمیخواند حذف میشود. مدیریت خطا