Vai al contenuto
Immagini e file

Immagini e file

Invia immagini con un messaggio: quali modelli le accettano, le forme ammesse e i loro limiti.

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

Un'immagine viaggia dentro un messaggio dell'utente, come una parte del suo content. L'esempio legge un file locale e lo invia come 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
  }
}

Quali modelli accettano immagini

Modelli Legge
shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro Immagini e documenti: PDF, Word, PowerPoint, Excel e file di testo semplice.
shannon-1.6-lite, shannon-1.6-pro Immagini.
shannon-2-lite, shannon-2-pro Immagini, nelle richieste che inviano anche tools o response_format.
Kimi-K3-3BIT-REAP, MiniMax-M3-3BIT-REAP, Kimi-K2.6-W4A16-AUTOROUND-REAP, inkling-W4A16-AUTOROUND-REAP, MiMo-V2.5-W8A16 Immagini.
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 Testo. Una richiesta con un'immagine riceve risposta con stato 400.
shannon-coder-1 Testo.

GET /v1/models riporta l'input di immagini per id come capabilities.vision. Modelli e prezzi

  • I modelli Shannon leggono i file dell'ultimo messaggio dell'utente. Metti l'immagine nel messaggio che la riguarda.
  • La famiglia Shannon 3 tiene in considerazione anche alcune immagini e documenti dei messaggi precedenti dell'utente, se sono stati inviati inline, e legge un numero massimo prefissato di immagini per richiesta, contate dalla prima.
  • I modelli open-weight ospitati leggono le immagini di ogni messaggio della conversazione.

Forme accettate

Un file viene inviato in uno di due modi: dentro la richiesta come base64, oppure come indirizzo che l'API recupera. Ogni file viaggia con la richiesta; l'API non ha un endpoint di upload.

Endpoint Nella richiesta (base64) Tramite indirizzo
/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://…"}}

Lo stesso messaggio dell'utente in ogni formato:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "What is in this picture?"},
    {
      "type": "image_url",
      "image_url": {
        "url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD…"
      }
    }
  ]
}
  • Un data URL ha la forma data:<media type>;base64,<data>. La parte ;base64 è obbligatoria.
  • Su /v1/chat/completions e /v1/responses, image_url può essere la stringa stessa o un oggetto {"url": "…"}.
  • Il tipo di file deriva dal data URL o da media_type. Senza di essi, un'immagine viene letta come image/png.
  • I file inline contano per la dimensione del corpo della richiesta, che può arrivare a 32 MiB.
  • Accettato per compatibilità: image_url.detail.

Limiti per i file remoti

Quando invii un indirizzo, l'API recupera il file prima che il modello venga eseguito, entro questi limiti:

Limite Regola
Dimensione Fino a 8 MiB per file.
Tempo 20 secondi per rispondere.
Reindirizzamenti Al massimo 5.
Indirizzo http:// o https://, senza nome utente o password nell'indirizzo, su un host con indirizzo pubblico.
Risposta dell'host Uno stato nella fascia 200 e un corpo non vuoto. Il tipo di file viene letto da Content-Type.
Richiesto come User-Agent: ShannonBot/1.0 (+https://shannon-ai.com)

Come contano le immagini in token

Sui modelli open-weight ospitati un'immagine conta un token per ogni patch di 28 × 28 pixel: la larghezza divisa per 28, arrotondata per eccesso, per l'altezza divisa per 28, arrotondata per eccesso. Il risultato fa parte di usage.prompt_tokens ed è fatturato come input.

1024 × 1024
1,369 token
1920 × 1080
2,691 token
512 × 512
361 token
  • Un'immagine remota viene recuperata prima, quindi viene contata la sua dimensione reale.
  • Un'immagine di cui non si può leggere la dimensione conta 1,024 token.
  • Gli endpoint di conteggio usano la stessa regola per i data URL. Non recuperano un indirizzo remoto e lo contano come 1,024 token. Conteggio dei token
  • Per un modello Shannon, leggi da usage nella risposta quanto è costata una richiesta con immagini.

Documenti e altri file

Anche la famiglia Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) legge i documenti. Il testo del documento viene estratto e dato al modello insieme al tuo messaggio.

Documento Tipo di 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

Un documento è una parte del messaggio dell'utente, come un'immagine:

Endpoint Nella richiesta (base64) Tramite indirizzo
/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."}
      ]
    }
  ]
}
  • Indica il tipo di media reale del file. Senza di esso, un documento viene letto come application/pdf.
  • Un file di testo semplice, come CSV, viene letto come testo e allegato allo stesso modo.
  • Quando un documento non può essere letto, o il file è di un altro tipo, il modello ne viene informato e può dirlo nella sua risposta. Lo stato è comunque 200.
  • Su ogni altro modello una parte documento viene esclusa da ciò che il modello legge, e la richiesta riceve risposta dal resto.
  • Un documento inviato tramite indirizzo viene recuperato entro i limiti per i file remoti indicati sopra.

Errori

Stato Tipo Messaggio Quando
400 invalid_request_error <id> does not accept image input È stata inviata un'immagine a un modello open-weight ospitato che accetta solo testo. Dal tuo saldo non viene prelevato nulla.
400 invalid_request_error audio and video input are not supported by any hosted model È stata inviata una parte audio o video a un modello open-weight ospitato.
413 invalid_request_error Failed to buffer the request body: … Il corpo della richiesta, con i suoi file inline, è più grande di 32 MiB. L'errore porta code: "request_too_large".

Un modello Shannon risponde con stato 200 qualunque file la richiesta porti: una parte che non legge viene esclusa. Gestione errori