Entrada de imagem

Anexo de arquivo (type: "file"): forneça um caminho absoluto; o runtime lê o arquivo do disco, converte-o em base64 e envia-o para o LLM.
Anexo binário (type: "blob"): forneça dados codificados em Base64 diretamente; útil quando a imagem já estiver na memória (por exemplo, capturas de tela, imagens geradas ou dados de uma API).

Overview

Diagrama: diagrama de sequência mostrando o processo descrito.

Conceito	Description
Anexo de arquivo	Um anexo com `type: "file"` e um absoluto `path` a uma imagem em disco
Anexo Blob	Um anexo com `type: "blob"`, codificado em base64 `data` e `mimeType`—sem necessidade de E/S de disco
Codificação automática	Para anexos de arquivo, o runtime lê a imagem e a converte em base64 automaticamente
Redimensionamento automático	O runtime redimensiona ou reduz automaticamente as imagens que excedem os limites específicos do modelo
Capacidade de visão	O modelo deve `capabilities.supports.vision = true` para processar imagens

Início rápido – anexo de arquivo

Anexe um arquivo de imagem a qualquer mensagem usando o tipo de anexo de arquivo. O caminho deve ser um caminho absoluto para uma imagem no disco.

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

Quando você já tiver dados de imagem na memória (por exemplo, uma captura de tela capturada pelo aplicativo ou uma imagem buscada de uma API), use um anexo de blob para enviá-los diretamente sem gravar em disco.

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

Formatos com suporte

Os formatos de imagem com suporte incluem JPG, PNG, GIF e outros tipos de imagem comuns. Para anexos de arquivo, o runtime lê a imagem do disco e a converte conforme necessário. Para anexos de blob, você fornece os dados base64 e o tipo MIME diretamente. Use PNG ou JPEG para obter melhores resultados, pois esses são os formatos mais amplamente compatíveis.

O campo do modelo capabilities.limits.vision.supported_media_types lista os tipos MIME exatos que ele aceita.

Processamento automático

O runtime processa automaticamente as imagens para se ajustarem às restrições do modelo. Nenhum redimensionamento manual é necessário.

As imagens que excedem a dimensão ou os limites de tamanho do modelo são redimensionadas automaticamente (preservando a proporção de aspecto) ou têm a qualidade reduzida.
Se uma imagem não puder ser trazida dentro dos limites após o processamento, ela será ignorada e não será enviada para a LLM.
O campo do modelo indica o tamanho máximo da capabilities.limits.vision.max_prompt_image_size imagem em bytes.

Você pode verificar esses limites em runtime por meio do objeto de funcionalidades do modelo. Para obter a melhor experiência, use imagens PNG ou JPEG de tamanho razoável.

Funcionalidades do modelo de visão

Nem todos os modelos dão suporte à visão. Verifique os recursos do modelo antes de enviar imagens.

Campos de funcionalidade

Campo	Tipo	Description
`capabilities.supports.vision`	`boolean`	Se o modelo pode processar entradas de imagem
`capabilities.limits.vision.supported_media_types`	`string[]`	Tipos MIME que o modelo aceita (por exemplo, `["image/png", "image/jpeg"]`)
`capabilities.limits.vision.max_prompt_images`	`number`	Número máximo de imagens por prompt
`capabilities.limits.vision.max_prompt_image_size`	`number`	Tamanho máximo da imagem em bytes

Tipo de limites de visão

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

Recebendo resultados de imagem

Quando as ferramentas retornam imagens (por exemplo, capturas de tela ou gráficos gerados), o resultado contém "image" blocos de conteúdo com dados codificados em base64.

Campo	Tipo	Description
`type`	`"image"`	Tipo de bloco de conteúdo discriminatório
`data`	`string`	Dados de imagem codificados em Base64
`mimeType`	`string`	Tipo MIME (por exemplo, `"image/png"`)

Os blocos de imagem aparecem nos resultados do evento tool.execution_complete. Consulte o guia Eventos de sessão de streaming para obter o ciclo de vida completo do evento.

Dicas e limitações

Dica	Detalhes
Usar PNG ou JPEG diretamente	Evita sobrecarga de conversão: eles são enviados para o LLM como estão.
Manter as imagens razoavelmente dimensionadas	Imagens grandes podem ter a qualidade reduzida, o que pode resultar na perda de detalhes importantes.
Usar caminhos absolutos para anexos de arquivo	O runtime lê arquivos do disco; caminhos relativos podem não ser resolvidos corretamente
Use anexos de blobs para dados em memória	Quando você já tem dados base64 (por exemplo, capturas de tela, respostas de API), o blob evita E/S de disco desnecessário
Verificar o suporte à visão primeiro	Enviar imagens para um modelo sem visão desperdiça tokens, pois não há compreensão visual.
Há suporte para várias imagens	Anexar vários anexos em uma mensagem, até o limite do `max_prompt_images` modelo
Não há suporte para SVG	Os arquivos SVG são baseados em texto e excluídos do processamento de imagem

Consulte também

Eventos de sessão de streaming: ciclo de vida do evento, incluindo blocos de conteúdo de resultado da ferramenta
Direção e fila: enviar mensagens de acompanhamento com anexos

Neste artigo