Entrée d’image

Pièce jointe de fichier (type: "file") : fournissez un chemin absolu ; le runtime lit le fichier à partir du disque, le convertit en base64 et l’envoie au LLM.
Pièce jointe blob (type: "blob") : fournir directement des données codées en Base64 ; utile si l’image est déjà en mémoire (p. ex., captures d’écran, images générées ou données provenant d’une API).

Overview

Diagramme : diagramme de séquence montrant le processus décrit.

Concept	Description
Pièce jointe de fichier	Une pièce jointe avec `type: "file"` et un chemin absolu `path` vers une image sur le disque.
Pièce jointe Blob	Pièce jointe avec `type: "blob"`, encodée en base64`data` et un `mimeType`— aucune opération d'E/S avec le disque n’est nécessaire.
Encodage automatique	Pour les pièces jointes de fichier, le runtime lit l’image et la convertit automatiquement en base64
Redimensionnement automatique	Le runtime redimensionne automatiquement ou réduit la qualité des images qui dépassent les limites spécifiques au modèle
Capacité de vision	Le modèle doit avoir `capabilities.supports.vision = true` pour traiter des images

Démarrage rapide — pièce jointe

Joignez un fichier image à n’importe quel message à l’aide du type de pièce jointe de fichier. Le chemin doit être un chemin absolu vers une image sur le disque.

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();
}

Démarrage rapide—pièce jointe blob

Lorsque vous disposez déjà de données d’image en mémoire (par exemple, une capture d’écran capturée par votre application ou une image extraite d’une API), utilisez une pièce jointe d’objet blob pour l’envoyer directement sans écrire sur le disque.

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();
}

Formats pris en charge

Les formats d’image pris en charge incluent JPG, PNG, GIF et d’autres types d’images courants. Pour les pièces jointes de fichier, le runtime lit l’image à partir du disque et la convertit en fonction des besoins. Pour les pièces jointes de blob, vous fournissez directement les données en base64 et le type MIME. Utilisez PNG ou JPEG pour obtenir des résultats optimaux, car il s’agit des formats les plus largement pris en charge.

Le champ du capabilities.limits.vision.supported_media_types modèle répertorie les types MIME exacts qu’il accepte.

Traitement automatique

Le runtime traite automatiquement les images en fonction des contraintes du modèle. Aucun redimensionnement manuel n’est requis.

Les images qui dépassent les limites de dimension ou de taille du modèle sont automatiquement redimensionnées (avec conservation des proportions) ou réduites en qualité.
Si une image ne peut pas être réduite dans les limites après traitement, elle est ignorée et n'est pas envoyée au LLM.
Le champ capabilities.limits.vision.max_prompt_image_size du modèle indique la taille maximale de l’image en octets.

Vous pouvez vérifier ces limites au moment de l’exécution via l’objet de fonctionnalités du modèle. Pour une expérience optimale, utilisez des images PNG ou JPEG de taille raisonnable.

Fonctionnalités du modèle vision

Tous les modèles ne prennent pas en charge la vision. Vérifiez les fonctionnalités du modèle avant d’envoyer des images.

Champs de capacité

Champ	Catégorie	Description
`capabilities.supports.vision`	`boolean`	Indique si le modèle peut traiter les entrées d’image
`capabilities.limits.vision.supported_media_types`	`string[]`	Types MIME que le modèle accepte (par exemple, `["image/png", "image/jpeg"]`)
`capabilities.limits.vision.max_prompt_images`	`number`	Nombre maximal d’images par invite
`capabilities.limits.vision.max_prompt_image_size`	`number`	Taille maximale de l’image en octets

Type de limites de vision

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

Réception des résultats d'image

Lorsque les outils retournent des images (par exemple, des captures d’écran ou des graphiques générés), le résultat contient des "image" blocs de contenu avec des données encodées en base64.

Champ	Catégorie	Description
`type`	`"image"`	Discriminateur de type de bloc de contenu
`data`	`string`	Données d’image encodées en base64
`mimeType`	`string`	Type MIME (par exemple, `"image/png"`)

Ces blocs d’images apparaissent dans les tool.execution_complete résultats des événements. Consultez le guide Événements de session de streaming pour le cycle de vie complet des événements.

Conseils et limitations

Tip	Détails
Utiliser PNG ou JPEG directement	Évite la surcharge de conversion : celles-ci sont envoyées telles quelles au LLM.
Conserver les images raisonnablement dimensionnées	Les grandes images peuvent être réduites de qualité, ce qui peut perdre des détails importants
Utiliser des chemins absolus pour les pièces jointes de fichier	Le runtime lit les fichiers à partir du disque ; les chemins relatifs peuvent ne pas être résolus correctement
Utiliser les pièces jointes blob pour les données en mémoire	Lorsque vous disposez déjà de données en base64 (par exemple, captures d’écran, réponses d’API), l’objet blob évite les E/S de disque inutiles
Vérifiez d'abord le support de la vision	L’envoi d’images à un modèle non destiné à la vision gaspille des jetons, car il ne peut pas comprendre visuellement.
Plusieurs images sont prises en charge	Joindre dans un message plusieurs pièces jointes, jusqu’à la limite du modèle `max_prompt_images`
SVG n’est pas pris en charge	Les fichiers SVG sont basés sur du texte et exclus du traitement d’images

Voir aussi

Événements de session de streaming : cycle de vie des événements, y compris les blocs de contenu des résultats de l’outil
Orientation et mise en file d'attente : envoi de messages de suivi avec des pièces jointes

Dans cet article