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) 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
}
} 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…"
}
}
]
} {
"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 có dạng
data:<media type>;base64,<data>. Phần;base64là bắt buộc. - Trên
/v1/chat/completionsvà/v1/responses,image_urlcó 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ừ
usagetrong 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 |
|---|---|
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."}
]
}
]
} {
"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."}
]
}
]
} - 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