Bildeingabe

Dateianhang (type: "file"): Geben Sie einen absoluten Pfad an; die Laufzeit liest die Datei von der Festplatte, konvertiert sie in Base64 und sendet sie an das LLM.
Blob-Anhang (type: "blob"): base64-kodierte Daten direkt bereitstellen; nützlich, wenn das Bild bereits im Speicher vorliegt (z. B. Screenshots, generierte Bilder oder Daten aus einer API).

Übersicht

Diagramm: Sequenzdiagramm mit dem beschriebenen Prozess.

Konzept	Description
Dateianhang	Ein Anhang mit `type: "file"` und ein absolutes `path` Bild auf einer Festplatte
Blob-Anhang	Eine Anlage mit `type: "blob"`, base64-codiertem `data` und einem `mimeType` – kein Festplatten-I/O erforderlich
Automatische Codierung	Bei Dateianlagen liest die Laufzeit das Bild und konvertiert es automatisch in Base64.
Automatische Größenänderung	Die Laufzeit ändert automatisch die Größe oder qualitätsmindert Bilder, die modellspezifische Grenzwerte überschreiten.
Vision-Funktion	Das Modell muss `capabilities.supports.vision = true` haben, um Bilder zu verarbeiten.

Schnellstart—Dateianhang

Fügen Sie eine Bilddatei an eine beliebige Nachricht an, indem Sie den Dateianhangstyp verwenden. Der Pfad muss ein absoluter Pfad zu einem Image auf dem Datenträger sein.

TypeScript

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();

const session = await client.createSession({
    model: "gpt-4.1",
    onPermissionRequest: async () => ({ kind: "approve-once" }),
});

await session.send({
    prompt: "Describe what you see in this image",
    attachments: [
        {
            type: "file",
            path: "/absolute/path/to/screenshot.png",
        },
    ],
});

Python

from copilot import CopilotClient, PermissionDecisionApproveOnce

client = CopilotClient()
await client.start()

session = await client.create_session(
    on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),
    model="gpt-4.1",
)

await session.send(
    "Describe what you see in this image",
    attachments=[
        {
            "type": "file",
            "path": "/absolute/path/to/screenshot.png",
        },
    ],
)

package main

import (
    "context"
    copilot "github.com/github/copilot-sdk/go"
    "github.com/github/copilot-sdk/go/rpc"
)

func main() {
    ctx := context.Background()
    client := copilot.NewClient(nil)
    client.Start(ctx)

    session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
        Model: "gpt-4.1",
        OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {
            return &rpc.PermissionDecisionApproveOnce{}, nil
        },
    })

    path := "/absolute/path/to/screenshot.png"
    session.Send(ctx, copilot.MessageOptions{
        Prompt: "Describe what you see in this image",
        Attachments: []copilot.Attachment{
            &copilot.UserMessageAttachmentFile{
                DisplayName: "screenshot.png",
                Path:        path,
            },
        },
    })
}

ctx := context.Background()
client := copilot.NewClient(nil)
client.Start(ctx)

session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
    Model: "gpt-4.1",
    OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {
        return &rpc.PermissionDecisionApproveOnce{}, nil
    },
})

path := "/absolute/path/to/screenshot.png"
session.Send(ctx, copilot.MessageOptions{
    Prompt: "Describe what you see in this image",
    Attachments: []copilot.Attachment{
        &copilot.UserMessageAttachmentFile{
            DisplayName: "screenshot.png",
            Path:        path,
        },
    },
})

.NET

using GitHub.Copilot;
using GitHub.Copilot.Rpc;

public static class ImageInputExample
{
    public static async Task Main()
    {
        await using var client = new CopilotClient();
        await using var session = await client.CreateSessionAsync(new SessionConfig
        {
            Model = "gpt-4.1",
            OnPermissionRequest = (req, inv) =>
                Task.FromResult(PermissionDecision.ApproveOnce()),
        });

        await session.SendAsync(new MessageOptions
        {
            Prompt = "Describe what you see in this image",
            Attachments = new List<UserMessageAttachment>
            {
                new UserMessageAttachmentFile
                {
                    Path = "/absolute/path/to/screenshot.png",
                    DisplayName = "screenshot.png",
                },
            },
        });
    }
}

using GitHub.Copilot;
using GitHub.Copilot.Rpc;

await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(new SessionConfig
{
    Model = "gpt-4.1",
    OnPermissionRequest = (req, inv) =>
        Task.FromResult(PermissionDecision.ApproveOnce()),
});

await session.SendAsync(new MessageOptions
{
    Prompt = "Describe what you see in this image",
    Attachments = new List<UserMessageAttachment>
    {
        new UserMessageAttachmentFile
        {
            Path = "/absolute/path/to/screenshot.png",
            DisplayName = "screenshot.png",
        },
    },
});

Java

import com.github.copilot.sdk.CopilotClient;
import com.github.copilot.sdk.events.*;
import com.github.copilot.sdk.json.*;
import java.util.List;

try (var client = new CopilotClient()) {
    client.start().get();

    var session = client.createSession(
        new SessionConfig()
            .setModel("gpt-4.1")
            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    ).get();

    session.send(new MessageOptions()
        .setPrompt("Describe what you see in this image")
        .setAttachments(List.of(
            new Attachment("file", "/absolute/path/to/screenshot.png", "screenshot.png")
        ))
    ).get();
}

Wenn Sie bereits Bilddaten im Arbeitsspeicher haben (z. B. einen Screenshot, der von Ihrer App erfasst wurde, oder ein Bild, das von einer API abgerufen wurde), verwenden Sie eine BLOB-Anlage, um sie direkt zu senden, ohne auf den Datenträger zu schreiben.

TypeScript

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();

const session = await client.createSession({
    model: "gpt-4.1",
    onPermissionRequest: async () => ({ kind: "approve-once" }),
});

const base64ImageData = "..."; // your base64-encoded image
await session.send({
    prompt: "Describe what you see in this image",
    attachments: [
        {
            type: "blob",
            data: base64ImageData,
            mimeType: "image/png",
            displayName: "screenshot.png",
        },
    ],
});

Python

from copilot import CopilotClient, PermissionDecisionApproveOnce

client = CopilotClient()
await client.start()

session = await client.create_session(
    on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),
    model="gpt-4.1",
)

base64_image_data = "..."  # your base64-encoded image
await session.send(
    "Describe what you see in this image",
    attachments=[
        {
            "type": "blob",
            "data": base64_image_data,
            "mimeType": "image/png",
            "displayName": "screenshot.png",
        },
    ],
)

package main

import (
    "context"
    copilot "github.com/github/copilot-sdk/go"
    "github.com/github/copilot-sdk/go/rpc"
)

func main() {
    ctx := context.Background()
    client := copilot.NewClient(nil)
    client.Start(ctx)

    session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
        Model: "gpt-4.1",
        OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {
            return &rpc.PermissionDecisionApproveOnce{}, nil
        },
    })

    base64ImageData := "..."
    mimeType := "image/png"
    displayName := "screenshot.png"
    session.Send(ctx, copilot.MessageOptions{
        Prompt: "Describe what you see in this image",
        Attachments: []copilot.Attachment{
            &copilot.UserMessageAttachmentBlob{
                Data:        base64ImageData,
                MIMEType:    mimeType,
                DisplayName: &displayName,
            },
        },
    })
}

mimeType := "image/png"
displayName := "screenshot.png"
session.Send(ctx, copilot.MessageOptions{
    Prompt: "Describe what you see in this image",
    Attachments: []copilot.Attachment{
        &copilot.UserMessageAttachmentBlob{
            Data:        base64ImageData, // base64-encoded string
            MIMEType:    mimeType,
            DisplayName: &displayName,
        },
    },
})

.NET

using GitHub.Copilot;
using GitHub.Copilot.Rpc;

public static class BlobAttachmentExample
{
    public static async Task Main()
    {
        await using var client = new CopilotClient();
        await using var session = await client.CreateSessionAsync(new SessionConfig
        {
            Model = "gpt-4.1",
            OnPermissionRequest = (req, inv) =>
                Task.FromResult(PermissionDecision.ApproveOnce()),
        });

        var base64ImageData = "...";
        await session.SendAsync(new MessageOptions
        {
            Prompt = "Describe what you see in this image",
            Attachments = new List<UserMessageAttachment>
            {
                new UserMessageAttachmentBlob
                {
                    Data = base64ImageData,
                    MimeType = "image/png",
                    DisplayName = "screenshot.png",
                },
            },
        });
    }
}

await session.SendAsync(new MessageOptions
{
    Prompt = "Describe what you see in this image",
    Attachments = new List<UserMessageAttachment>
    {
        new UserMessageAttachmentBlob
        {
            Data = base64ImageData,
            MimeType = "image/png",
            DisplayName = "screenshot.png",
        },
    },
});

Java

import com.github.copilot.sdk.CopilotClient;
import com.github.copilot.sdk.events.*;
import com.github.copilot.sdk.json.*;
import java.util.List;

try (var client = new CopilotClient()) {
    client.start().get();

    var session = client.createSession(
        new SessionConfig()
            .setModel("gpt-4.1")
            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    ).get();

    var base64ImageData = "..."; // your base64-encoded image
    session.send(new MessageOptions()
        .setPrompt("Describe what you see in this image")
        .setAttachments(List.of(
            new BlobAttachment()
                .setData(base64ImageData)
                .setMimeType("image/png")
                .setDisplayName("screenshot.png")
        ))
    ).get();
}

Unterstützte Formate

Unterstützte Bildformate umfassen JPG, PNG, GIF und andere gängige Bildtypen. Bei Dateianhängen liest die Laufzeitumgebung das Bild vom Datenträger und konvertiert es bei Bedarf. Für Blob-Anhänge stellen Sie die Base64-Daten und den MIME-Typ direkt bereit. Verwenden Sie PNG oder JPEG, um optimale Ergebnisse zu erzielen, da dies die am häufigsten unterstützten Formate sind.

Das Feld des capabilities.limits.vision.supported_media_types Modells listet die genauen MIME-Typen auf, die es akzeptiert.

Automatische Verarbeitung

Die Laufzeit verarbeitet automatisch Bilder, die in die Einschränkungen des Modells passen. Es ist keine manuelle Größenänderung erforderlich.

Bilder, die die Größenbeschränkungen des Modells überschreiten, werden automatisch angepasst (Seitenverhältnis beibehalten) oder die Qualität wird verringert.
Wenn ein Bild nach der Verarbeitung nicht innerhalb von Grenzen gebracht werden kann, wird es übersprungen und nicht an die LLM gesendet.
Das Feld des capabilities.limits.vision.max_prompt_image_size Modells gibt die maximale Bildgröße in Bytes an.

Sie können diese Grenzwerte zur Laufzeit über das Modellfunktionen-Objekt überprüfen. Um optimale Ergebnisse zu erzielen, verwenden Sie PNG- oder JPEG-Bilder in angemessener Größe.

Vision-Modellfunktionen

Nicht alle Modelle unterstützen die Bildverarbeitung. Überprüfen Sie die Funktionen des Modells, bevor Sie Bilder senden.

Funktionsfelder

Feld	Typ	Description
`capabilities.supports.vision`	`boolean`	Gibt an, ob das Modell Bildeingaben verarbeiten kann.
`capabilities.limits.vision.supported_media_types`	`string[]`	MIME-Typen, die das Modell akzeptiert (z. B. `["image/png", "image/jpeg"]`)
`capabilities.limits.vision.max_prompt_images`	`number`	Maximale Anzahl von Bildern pro Eingabeaufforderung
`capabilities.limits.vision.max_prompt_image_size`	`number`	Maximale Bildgröße in Byte

Typ der Vision-Grenzwerte

interface VisionCapabilities {
    vision?: {
        supported_media_types: string[];
        max_prompt_images: number;
        max_prompt_image_size: number; // bytes
    };
}

vision?: {
    supported_media_types: string[];
    max_prompt_images: number;
    max_prompt_image_size: number; // bytes
};

Empfangen von Bildergebnissen

Wenn Tools Bilder zurückgeben (z. B. Screenshots oder generierte Diagramme), enthält "image" das Ergebnis Inhaltsblöcke mit base64-codierten Daten.

Feld	Typ	Description
`type`	`"image"`	Diskriminator des Inhaltsblocktyps
`data`	`string`	Base64-codierte Bilddaten
`mimeType`	`string`	MIME-Typ (z. B. `"image/png"`)

Diese Bildblöcke werden in tool.execution_complete Ereignisergebnissen angezeigt. Lesen Sie den AUTOTITLE-Leitfaden für den vollständigen Ereignislebenszyklus.

Tipps und Einschränkungen

Tip	Details
Direktes Verwenden von PNG oder JPEG	Vermeidung von Konvertierungsaufwand – diese werden unverändert an das LLM gesendet.
Halten Sie Bilder in angemessener Größe	Große Bilder können qualitätsmindert sein, was wichtige Details verlieren kann
Verwenden Sie absolute Pfade für Dateianhänge	Die Laufzeit liest Dateien vom Datenträger, relative Pfade werden möglicherweise nicht ordnungsgemäß aufgelöst
Verwendung von BLOB-Anhängen für im Arbeitsspeicher gehaltene Daten	Wenn Sie bereits base64-Daten haben (z. B. Screenshots, API-Antworten), vermeidet BLOB unnötige Datenträger-E/A
Überprüfen der Sehunterstützung zuerst	Das Senden von Bildern an ein Nicht-Vision-Modell, das kein visuelles Verständnis hat, verschwendet Token.
Mehrere Bilder werden unterstützt.	Anfügen mehrerer Anlagen in einer Nachricht bis zum Grenzwert des `max_prompt_images` Modells
SVG wird nicht unterstützt	SVG-Dateien sind textbasiert und von der Bildverarbeitung ausgeschlossen.

Siehe auch

Ereignisse einer Streaming-Sitzung: Lebenszyklus von Ereignissen einschließlich Inhaltsblöcken von Tool-Ergebnissen
Steuerung und Warteschlangen: Senden von Nachverfolgungsnachrichten mit Anlagen

In diesem Artikel