Uso de la entrada de imagen con el SDK de Copilot

Nota:

          SDK de Copilot actualmente está en Versión preliminar técnica. La funcionalidad y la disponibilidad están sujetas a cambios.

Hay dos maneras de adjuntar imágenes a una SDK de Copilot sesión:

        **Adjunto de archivo** (`type: "file"`): proporcione una ruta completa; en tiempo de ejecución, se lee el archivo del disco, se convierte a base64 y se envía al LLM.

        **Blob attachment** (`type: "blob"`): proporciona datos codificados en base64 directamente; es útil cuando la imagen ya está en memoria (por ejemplo, capturas de pantalla, imágenes generadas o datos de una API).

Para obtener un diagrama de secuencia del flujo de entrada de imagen, consulte el github/copilot-sdk repositorio.

Concepto	Descripción

          **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.

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: "approved" }),
});

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

Para obtener ejemplos en Python, Go y .NET, consulte el github/copilot-sdk repositorio.

Inicio rápido: adjuntar blobs

Cuando ya tenga datos de imagen en 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.

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: "approved" }),
});

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",
        },
    ],
});

Para obtener ejemplos en Python, Go y .NET, consulte el github/copilot-sdk repositorio.

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.

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	Descripción
`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

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	Descripción
`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. Para obtener más información, vea Streaming de eventos en el SDK de Copilot.

Sugerencias y limitaciones

Sugerencia	Detalles

          **Uso de PNG o JPEG** | 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 |

Lectura adicional

        [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/streaming-events): ciclo de vida de eventos, incluidos bloques de contenido de resultados de herramientas

        [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-copilot-sdk/steering-and-queueing): envío de mensajes de seguimiento con datos adjuntos