Imagini și fișiere
Trimite imagini împreună cu un mesaj: ce modele le acceptă, formele acceptate și limitele lor.
POST https://api.shannon-ai.com/v1/chat/completions
O imagine călătorește în interiorul unui mesaj al utilizatorului, ca o parte a content. Exemplul citește un fișier local și îl trimite ca 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
}
} Ce modele acceptă imagini
| Modele | Citește |
|---|---|
shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro | Imagini și documente: fișiere PDF, Word, PowerPoint, Excel și text simplu. |
shannon-1.6-lite, shannon-1.6-pro | Imagini. |
shannon-2-lite, shannon-2-pro | Imagini, în cereri care trimit și tools sau response_format. |
Kimi-K3-3BIT-REAP, MiniMax-M3-3BIT-REAP, Kimi-K2.6-W4A16-AUTOROUND-REAP, inkling-W4A16-AUTOROUND-REAP, MiMo-V2.5-W8A16 | Imagini. |
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 | Text. O cerere cu o imagine primește răspuns cu starea 400. |
shannon-coder-1 | Text. |
GET /v1/models raportează intrarea de imagini pentru fiecare id ca capabilities.vision. Modele și prețuri
- Modelele Shannon citesc fișierele din ultimul mesaj al utilizatorului. Pune imaginea în mesajul care întreabă despre ea.
- Familia Shannon 3 păstrează în vedere și câteva imagini și documente din mesajele anterioare ale utilizatorului, dacă au fost trimise inline, și citește un număr maxim fix de imagini per cerere, numărate de la prima.
- Modelele open-weight găzduite citesc imaginile din toate mesajele conversației.
Forme acceptate
Un fișier este trimis în unul din două moduri: în interiorul cererii, ca base64, sau ca adresă pe care API-ul o preia. Fiecare fișier călătorește odată cu cererea; API-ul nu are endpoint de încărcare.
| Endpoint | În cerere (base64) | Prin adresă |
|---|---|---|
/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://…"}} |
Același mesaj al utilizatorului în fiecare format:
{
"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…"
}
}
]
} - Un data URL are forma
data:<media type>;base64,<data>. Partea;base64este obligatorie. - Pe
/v1/chat/completionsși/v1/responses,image_urlpoate fi chiar șirul sau un obiect{"url": "…"}. - Tipul fișierului provine din data URL sau din
media_type. Fără el, o imagine este citită caimage/png. - Fișierele incluse în cerere se numără la dimensiunea corpului cererii, care poate fi de până la 32 MiB.
- Acceptat pentru compatibilitate:
image_url.detail.
Limite pentru fișierele la distanță
Când trimiți o adresă, API-ul descarcă fișierul înainte de rularea modelului, în aceste limite:
| Limită | Regulă |
|---|---|
| Dimensiune | Până la 8 MiB per fișier. |
| Timp | 20 de secunde pentru a răspunde. |
| Redirecționări | Cel mult 5. |
| Adresă | http:// sau https://, fără nume de utilizator sau parolă în adresă, pe o gazdă cu adresă publică. |
| Răspunsul gazdei | O stare din seria 200 și un corp care nu este gol. Tipul fișierului este citit din Content-Type. |
| Cerut ca | User-Agent: ShannonBot/1.0 (+https://shannon-ai.com) |
Cum se numără imaginile în token-uri
La modelele open-weight găzduite, o imagine contează cu un token pentru fiecare porțiune de 28 × 28 pixeli: lățimea împărțită la 28, rotunjită în sus, înmulțită cu înălțimea împărțită la 28, rotunjită în sus. Rezultatul face parte din usage.prompt_tokens și este facturat ca intrare.
- 1024 × 1024
- 1,369 token-uri
- 1920 × 1080
- 2,691 token-uri
- 512 × 512
- 361 token-uri
- O imagine la distanță este descărcată mai întâi, deci se numără dimensiunea ei reală.
- O imagine a cărei dimensiune nu poate fi citită contează 1,024 token-uri.
- Endpoint-urile de numărare aplică aceeași regulă pentru data URL-uri. Ele nu descarcă o adresă la distanță și o numără ca 1,024 token-uri. Numărarea token-urilor
- Pentru un model Shannon, citește costul unei cereri cu imagini din
usagedin răspuns.
Documente și alte fișiere
Familia Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) citește și documente. Textul documentului este extras și dat modelului împreună cu mesajul tău.
| Document | Tip media |
|---|---|
application/pdf | |
| Word | application/vnd.openxmlformats-officedocument.wordprocessingml.document |
| PowerPoint | application/vnd.openxmlformats-officedocument.presentationml.presentation |
| Excel | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
Un document este o parte a mesajului utilizatorului, ca o imagine:
| Endpoint | În cerere (base64) | Prin adresă |
|---|---|---|
/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."}
]
}
]
} - Indică tipul media real al fișierului. Fără el, un document este citit ca
application/pdf. - Un fișier text simplu, cum ar fi CSV, este citit ca text și atașat în același mod.
- Când un document nu poate fi citit sau fișierul este de alt tip, modelul este informat și poate spune asta în răspuns. Starea este totuși
200. - Pe orice alt model, o parte de tip document este omisă din ce citește modelul, iar cererea primește răspuns pe baza restului.
- Un document trimis prin adresă este preluat conform limitelor pentru fișiere la distanță de mai sus.
Erori
| Stare | Tip | Mesaj | Când |
|---|---|---|---|
400 | invalid_request_error | <id> does not accept image input | O imagine a fost trimisă unui model open-weight găzduit care acceptă doar text. Nu se scade nimic din soldul tău. |
400 | invalid_request_error | audio and video input are not supported by any hosted model | O parte audio sau video a fost trimisă unui model open-weight găzduit. |
413 | invalid_request_error | Failed to buffer the request body: … | Corpul cererii, cu fișierele sale incluse, este mai mare de 32 MiB. Eroarea poartă code: "request_too_large". |
Un model Shannon răspunde cu starea 200 indiferent ce fișiere poartă cererea: o parte pe care nu o citește este omisă. Gestionare erori