Chuyển đến nội dung
Hình ảnh và tệp

Hình ảnh và tệp

Gửi hình ảnh cùng tin nhắn: model nào nhận chúng, các dạng được chấp nhận và giới hạn của chúng.

POST https://api.shannon-ai.com/v1/chat/completions

Một hình ảnh đi trong tin nhắn người dùng, như một phần của content. Mẫu đọc một tệp cục bộ và gửi nó dưới dạng 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
  }
}

Model nào nhận hình ảnh

Model Đọc
shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro Hình ảnh và tài liệu: PDF, Word, PowerPoint, Excel và tệp văn bản thuần.
shannon-1.6-lite, shannon-1.6-pro Hình ảnh.
shannon-2-lite, shannon-2-pro Hình ảnh, trong các yêu cầu cũng gửi tools hoặc response_format.
Kimi-K3-3BIT-REAP, MiniMax-M3-3BIT-REAP, Kimi-K2.6-W4A16-AUTOROUND-REAP, inkling-W4A16-AUTOROUND-REAP, MiMo-V2.5-W8A16 Hình ảnh.
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 Văn bản. Yêu cầu có hình ảnh được trả lời với trạng thái 400.
shannon-coder-1 Văn bản.

GET /v1/models báo đầu vào hình ảnh theo từng id dưới dạng capabilities.vision. Model và giá

  • Các model Shannon đọc các tệp của tin nhắn người dùng cuối cùng. Hãy đặt hình ảnh vào tin nhắn hỏi về nó.
  • Dòng Shannon 3 cũng giữ trong tầm nhìn một vài hình ảnh và tài liệu của các tin nhắn người dùng trước đó nếu chúng được gửi inline, và đọc một số lượng hình ảnh tối đa nhất định cho mỗi yêu cầu, đếm từ hình đầu tiên.
  • Các model open-weight hosted đọc hình ảnh của mọi tin nhắn trong cuộc hội thoại.

Các dạng được chấp nhận

Một tệp được gửi theo một trong hai cách: nhúng trong yêu cầu dưới dạng base64, hoặc dưới dạng địa chỉ mà API tải về. Mọi tệp đều đi cùng yêu cầu; API không có endpoint tải lên.

Endpoint Trong yêu cầu (base64) Qua địa chỉ
/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://…"}}

Cùng một tin nhắn người dùng trong từng định dạng:

{
  "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 có dạng data:<media type>;base64,<data>. Phần ;base64 là bắt buộc.
  • Trên /v1/chat/completions và /v1/responses, image_url có thể là chính chuỗi đó hoặc một đối tượng {"url": "…"}.
  • Loại tệp lấy từ data URL hoặc từ media_type. Nếu không có, hình ảnh được đọc như image/png.
  • Các tệp nhúng được tính vào kích thước nội dung yêu cầu, có thể lên tới 32 MiB.
  • Được chấp nhận để tương thích: image_url.detail.

Giới hạn cho tệp từ xa

Khi bạn gửi một địa chỉ, API tải tệp về trước khi model chạy, trong các giới hạn sau:

Giới hạn Quy tắc
Kích thước Tối đa 8 MiB cho mỗi tệp.
Thời gian 20 giây để phản hồi.
Chuyển hướng Tối đa 5.
Địa chỉ http:// hoặc https://, không có tên người dùng hay mật khẩu trong địa chỉ, trên một host có địa chỉ công khai.
Phản hồi của host Một trạng thái trong dải 200 và nội dung không rỗng. Loại tệp được đọc từ Content-Type.
Được yêu cầu với User-Agent: ShannonBot/1.0 (+https://shannon-ai.com)

Cách hình ảnh được tính thành token

Trên các model open-weight hosted, một hình ảnh được tính một token cho mỗi ô 28 × 28 pixel: chiều rộng chia 28, làm tròn lên, nhân với chiều cao chia 28, làm tròn lên. Kết quả là một phần của usage.prompt_tokens và được tính phí như đầu vào.

1024 × 1024
1,369 token
1920 × 1080
2,691 token
512 × 512
361 token
  • Hình ảnh từ xa được tải về trước, nên kích thước thực của nó được tính.
  • Hình ảnh không đọc được kích thước được tính là 1,024 token.
  • Các endpoint đếm dùng cùng quy tắc cho data URL. Chúng không tải một địa chỉ từ xa và tính nó là 1,024 token. Đếm token
  • Với model Shannon, hãy đọc chi phí của một yêu cầu có hình ảnh từ usage trong phản hồi.

Tài liệu và các tệp khác

Dòng Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) còn đọc được tài liệu. Văn bản của tài liệu được trích ra và đưa cho model cùng với tin nhắn của bạn.

Tài liệu Kiểu media
PDF application/pdf
Word application/vnd.openxmlformats-officedocument.wordprocessingml.document
PowerPoint application/vnd.openxmlformats-officedocument.presentationml.presentation
Excel application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Tài liệu là một phần của tin nhắn người dùng, giống như hình ảnh:

Endpoint Trong yêu cầu (base64) Qua địa chỉ
/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."}
      ]
    }
  ]
}
  • Hãy đưa kiểu media thật của tệp. Nếu không có, tài liệu được đọc như application/pdf.
  • Tệp văn bản thuần, như CSV, được đọc như văn bản và đính kèm theo cùng cách.
  • Khi không đọc được tài liệu, hoặc tệp thuộc loại khác, model được báo như vậy và có thể nói điều đó trong câu trả lời. Trạng thái vẫn là 200.
  • Trên mọi model khác, phần tài liệu bị loại khỏi những gì model đọc, và yêu cầu được trả lời từ phần còn lại.
  • Tài liệu gửi qua địa chỉ được tải về theo các giới hạn dành cho tệp từ xa ở trên.

Lỗi

Trạng thái Loại Thông báo Khi nào
400 invalid_request_error <id> does not accept image input Một hình ảnh đã được gửi tới model open-weight hosted chỉ nhận văn bản. Không có khoản nào bị trừ khỏi số dư của bạn.
400 invalid_request_error audio and video input are not supported by any hosted model Một phần âm thanh hoặc video đã được gửi tới model open-weight hosted.
413 invalid_request_error Failed to buffer the request body: … Nội dung yêu cầu, cùng các tệp nhúng trong đó, lớn hơn 32 MiB. Lỗi mang code: "request_too_large".

Model Shannon trả lời với trạng thái 200 bất kể yêu cầu mang tệp nào: phần mà nó không đọc sẽ bị loại bỏ. Xử lý lỗi