Afbeeldingen en bestanden

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

Een afbeelding reist mee in een gebruikersbericht, als een onderdeel van zijn content. Het voorbeeld leest een lokaal bestand en verstuurt het als 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
  }
}

Welke modellen afbeeldingen accepteren

GET /v1/models meldt afbeeldingsinput per id als capabilities.vision. Modellen en prijzen

• De Shannon-modellen lezen de bestanden van het laatste gebruikersbericht. Zet de afbeelding in het bericht dat erover vraagt.
• De Shannon 3-familie houdt ook enkele afbeeldingen en documenten uit eerdere gebruikersberichten in beeld als die inline zijn verstuurd, en leest per aanvraag een vast maximumaantal afbeeldingen, geteld vanaf de eerste.
• De gehoste open-weight modellen lezen de afbeeldingen van elk bericht in het gesprek.

Geaccepteerde vormen

Een bestand wordt op een van twee manieren verstuurd: in de aanvraag als base64, of als adres dat de API ophaalt. Elk bestand reist mee met de aanvraag; de API heeft geen upload-endpoint.

Hetzelfde gebruikersbericht in elk formaat:

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

• Een data-URL heeft de vorm data:<media type>;base64,<data>. Het deel ;base64 is verplicht.
• Op /v1/chat/completions en /v1/responses kan image_url de string zelf zijn of een object {"url": "…"}.
• Het bestandstype komt uit de data-URL of uit media_type. Zonder type wordt een afbeelding gelezen als image/png.
• Inline bestanden tellen mee voor de grootte van de request-body, die tot 32 MiB mag zijn.
• Geaccepteerd voor compatibiliteit: image_url.detail.

Limieten voor externe bestanden

Als je een adres verstuurt, haalt de API het bestand op voordat het model draait, binnen deze limieten:

Hoe afbeeldingen in tokens tellen

Op de gehoste open-weight modellen telt een afbeelding één token per patch van 28 × 28 pixels: de breedte gedeeld door 28, naar boven afgerond, maal de hoogte gedeeld door 28, naar boven afgerond. Het resultaat is onderdeel van usage.prompt_tokens en wordt als input gefactureerd.

1024 × 1024

1,369 tokens

1920 × 1080

2,691 tokens

512 × 512

361 tokens

• Een externe afbeelding wordt eerst opgehaald, dus de echte grootte wordt geteld.
• Een afbeelding waarvan de grootte niet gelezen kan worden, telt als 1,024 tokens.
• De telendpoints gebruiken dezelfde regel voor data-URL's. Ze halen een extern adres niet op en tellen het als 1,024 tokens. Tokens tellen
• Lees bij een Shannon-model in usage van het antwoord wat een aanvraag met afbeeldingen heeft gekost.

Documenten en andere bestanden

De Shannon 3-familie (shannon-3, shannon-3-pro, shannon-3.1, shannon-3.1-pro) leest ook documenten. De tekst van het document wordt eruit gehaald en samen met je bericht aan het model gegeven.

Een document is een onderdeel van het gebruikersbericht, net als een afbeelding:

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

• Geef het echte mediatype van het bestand op. Zonder mediatype wordt een document gelezen als application/pdf.
• Een platte-tekstbestand, zoals CSV, wordt als tekst gelezen en op dezelfde manier bijgevoegd.
• Als een document niet gelezen kan worden, of het bestand van een ander type is, krijgt het model dat te horen en kan het dat in zijn antwoord zeggen. De status is nog steeds 200.
• Op elk ander model wordt een documentonderdeel weggelaten uit wat het model leest, en wordt de aanvraag beantwoord met de rest.
• Een document dat via een adres wordt verstuurd, wordt opgehaald binnen de bovenstaande limieten voor externe bestanden.

Fouten

Een Shannon-model antwoordt met status 200, welke bestanden de aanvraag ook bevat: een onderdeel dat het niet leest, wordt weggelaten. Foutafhandeling