Entrada de imagen

Archivo adjunto (type: "file"): proporcione una ruta absoluta; el entorno de ejecución lee el archivo del disco, lo convierte a base64 y lo envía al LLM.
Adjunto blob (type: "blob"): proporcione directamente datos codificados en base64; es útil cuando la imagen ya está en memoria (por ejemplo, capturas de pantalla, imágenes generadas o datos de una API).

Visión general

Diagrama: diagrama de secuencia que muestra el proceso descrito.

Concepto	Description
Archivo adjunto	Un adjunto con `type: "file"` y una ruta absoluta `path` a una imagen en disco
Datos adjuntos de blobs	Un adjunto con `type: "blob"`, codificado en base64 `data` y sin necesidad de `mimeType` de E/S de disco
Codificación automática	En el caso de los archivos adjuntos, el tiempo de ejecución lee la imagen y la convierte automáticamente en base64.
Cambio de tamaño automático	El tiempo de ejecución cambia automáticamente el tamaño o reduce la calidad de las imágenes que superan los límites específicos del modelo.
Funcionalidad de visión	El modelo debe disponer de `capabilities.supports.vision = true` para procesar imágenes

Inicio rápido: archivo adjunto

Adjunte un archivo de imagen a cualquier mensaje mediante el tipo de archivo adjunto. La ruta de acceso debe ser una ruta de acceso absoluta a una imagen en el 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();
}

Inicio rápido: datos adjuntos de blob

Cuando ya tenga datos de imagen en la memoria (por ejemplo, una captura de pantalla capturada por la aplicación o una imagen capturada de una API), use un archivo adjunto de blob para enviarlo directamente sin escribir en el 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 compatibles

Los formatos de imagen admitidos incluyen JPG, PNG, GIF y otros tipos de imágenes comunes. En el caso de los archivos adjuntos, el tiempo de ejecución lee la imagen del disco y la convierte según sea necesario. En el caso de los datos adjuntos de blob, proporcione los datos base64 y el tipo MIME directamente. Use PNG o JPEG para obtener los mejores resultados, ya que son los formatos más compatibles.

El campo del capabilities.limits.vision.supported_media_types modelo enumera los tipos MIME exactos que acepta.

Procesamiento automático

El tiempo de ejecución procesa automáticamente las imágenes para que se ajusten a las restricciones del modelo. No es necesario cambiar el tamaño manual.

Las imágenes que superan los límites de dimensión o tamaño del modelo se cambian automáticamente de tamaño (conservando la relación de aspecto) o reducen la calidad.
Si una imagen no se puede ajustar a los límites después del procesamiento, se omite y no se envía al LLM.
El campo del modelo capabilities.limits.vision.max_prompt_image_size indica el tamaño máximo de la imagen en bytes.

Puede comprobar estos límites en tiempo de ejecución mediante el objeto de funcionalidades del modelo. Para obtener la mejor experiencia, use imágenes PNG o JPEG de tamaño razonable.

Funcionalidades del modelo de visión

No todos los modelos admiten la visión. Compruebe las funcionalidades del modelo antes de enviar imágenes.

Campos de funcionalidad

Campo	Tipo	Description
`capabilities.supports.vision`	`boolean`	Si el modelo puede procesar entradas de imagen
`capabilities.limits.vision.supported_media_types`	`string[]`	Tipos MIME que acepta el modelo (por ejemplo, `["image/png", "image/jpeg"]`)
`capabilities.limits.vision.max_prompt_images`	`number`	Número máximo de imágenes por solicitud
`capabilities.limits.vision.max_prompt_image_size`	`number`	Tamaño máximo de imagen en bytes

Tipo de límites de visión

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

Recepción de los resultados de la imagen

Cuando las herramientas devuelven imágenes (por ejemplo, capturas de pantalla o gráficos generados), el resultado contiene "image" bloques de contenido con datos codificados en base64.

Campo	Tipo	Description
`type`	`"image"`	Discriminador de tipo de bloque de contenido
`data`	`string`	Datos de imagen codificados en Base64
`mimeType`	`string`	Tipo MIME (por ejemplo, `"image/png"`)

Estos bloques de imagen aparecen en tool.execution_complete los resultados del evento. Consulte la guía Eventos de la sesión de transmisión para obtener el ciclo de vida completo de los eventos.

Sugerencias y limitaciones

Tip	Detalles
Usar PNG o JPEG directamente	Evita la sobrecarga de conversión: estas se envían al LLM tal cual.
Mantener imágenes de tamaño razonable	Las imágenes grandes pueden reducir la calidad, lo que puede perder detalles importantes.
Utilice rutas de acceso absolutas para los archivos adjuntos	El entorno de ejecución lee los archivos del disco; es posible que las rutas de acceso relativas no se resuelvan correctamente.
Usa datos adjuntos de blob para datos en memoria	Cuando ya tiene datos base64 (por ejemplo, capturas de pantalla, respuestas de API), el blob evita E/S de disco innecesario.
Comprobación de la compatibilidad con la visión en primer lugar	El envío de imágenes a un modelo que no está diseñado para la visión implica un desperdicio de tokens debido a la ausencia de una interpretación visual.
Se admiten varias imágenes	Adjunte varios archivos adjuntos en un mensaje, hasta el límite del `max_prompt_images` modelo.
SVG no se admite	Los archivos SVG se basan en texto y se excluyen del procesamiento de imágenes

Consulte también

Eventos de la sesión de transmisión: ciclo de vida de eventos, incluidos bloques de contenido de resultados de herramientas
Dirección y puesta en cola: envío de mensajes de seguimiento con datos adjuntos

En este artículo