Images et fichiers

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

Une image voyage dans un message utilisateur, comme une partie de son content. L'exemple lit un fichier local et l'envoie sous forme d'URL de données.

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
  }
}

Quels modèles acceptent les images

GET /v1/models indique l'entrée image par id sous la forme capabilities.vision. Modèles et tarifs

• Les modèles Shannon lisent les fichiers du dernier message utilisateur. Placez l'image dans le message qui pose la question.
• La famille Shannon 3 garde aussi en vue quelques images et documents des messages utilisateur précédents lorsqu'ils ont été envoyés en ligne, et lit un nombre maximal fixé d'images par requête, comptées à partir de la première.
• Les modèles open-weight hébergés lisent les images de chaque message de la conversation.

Formes acceptées

Un fichier est envoyé de l'une de deux façons : dans la requête en base64, ou sous forme d'adresse que l'API récupère. Chaque fichier voyage avec la requête ; l'API n'a pas de point de terminaison d'envoi.

Le même message utilisateur dans chaque 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…"
      }
    }
  ]
}

• Une URL de données a la forme data:<media type>;base64,<data>. La partie ;base64 est obligatoire.
• Sur /v1/chat/completions et /v1/responses, image_url peut être la chaîne elle-même ou un objet {"url": "…"}.
• Le type de fichier provient de l'URL de données ou de media_type. Sans type, une image est lue comme image/png.
• Les fichiers en ligne comptent dans la taille du corps de la requête, qui peut atteindre 32 MiB.
• Accepté pour la compatibilité : image_url.detail.

Limites des fichiers distants

Quand vous envoyez une adresse, l'API récupère le fichier avant l'exécution du modèle, dans ces limites :

Comment les images sont comptées en tokens

Sur les modèles open-weight hébergés, une image compte un token par bloc de 28 × 28 pixels : la largeur divisée par 28, arrondie au supérieur, multipliée par la hauteur divisée par 28, arrondie au supérieur. Le résultat fait partie de usage.prompt_tokens et est facturé comme entrée.

1024 × 1024

1,369 tokens

1920 × 1080

2,691 tokens

512 × 512

361 tokens

• Une image distante est d'abord récupérée, c'est donc sa taille réelle qui est comptée.
• Une image dont la taille ne peut pas être lue compte pour 1,024 tokens.
• Les points de terminaison de comptage appliquent la même règle aux URL de données. Ils ne récupèrent pas une adresse distante et la comptent pour 1,024 tokens. Décompte de tokens
• Pour un modèle Shannon, lisez ce qu'a coûté une requête avec des images dans usage de la réponse.

Documents et autres fichiers

La famille Shannon 3 (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) lit aussi les documents. Le texte du document est extrait et donné au modèle avec votre message.

Un document est une partie du message utilisateur, comme une image :

{
  "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."}
      ]
    }
  ]
}

• Indiquez le véritable type de média du fichier. Sans type, un document est lu comme application/pdf.
• Un fichier en texte brut, comme un CSV, est lu comme du texte et joint de la même manière.
• Quand un document ne peut pas être lu, ou que le fichier est d'un autre type, le modèle en est informé et peut le dire dans sa réponse. Le statut reste 200.
• Sur tout autre modèle, une partie document est retirée de ce que lit le modèle, et la requête reçoit une réponse fondée sur le reste.
• Un document envoyé par adresse est récupéré selon les limites des fichiers distants ci-dessus.

Erreurs

Un modèle Shannon répond avec le statut 200 quels que soient les fichiers de la requête : une partie qu'il ne lit pas est retirée. Gestion des erreurs