رفتن به محتوا
تصاویر و فایل‌ها

تصاویر و فایل‌ها

تصاویر را همراه پیام بفرستید: کدام مدل‌ها آن‌ها را می‌پذیرند، شکل‌های پذیرفته‌شده و محدودیت‌هایشان.

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)
200 JSON
{
  "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…"
      }
    }
  ]
}
  • 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) اسناد را هم می‌خواند. متن سند استخراج می‌شود و همراه پیام شما به مدل داده می‌شود.

سند نوع رسانه
PDF 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."}
      ]
    }
  ]
}
  • نوع رسانه واقعی فایل را بدهید. بدون آن، سند به‌صورت 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 پاسخ می‌دهد: بخشی که نمی‌خواند حذف می‌شود. مدیریت خطا