画像入力

添付ファイルとしてCopilotセッションに画像を送信します。 画像を添付するには、次の 2 つの方法があります。

この記事で

  • 添付ファイル (type: "file"): 絶対パスを指定します。ランタイムはファイルをディスクから読み取り、base64 に変換して LLM に送信します。
  • BLOB 添付ファイル (type: "blob"): base64 でエンコードされたデータを直接提供します。画像が既にメモリ内にある場合に便利です (スクリーンショット、生成された画像、API からのデータなど)。

Overview

図: 説明されたプロセスを示すシーケンス図。

概念Description
添付ファイル
type: "file"とディスク上のイメージへの絶対pathを含む添付ファイル
BLOB の添付ファイル
type: "blob"、base64 でエンコードされたdata、およびmimeTypeを含む添付ファイル 。ディスク I/O は必要ありません
自動エンコード添付ファイルの場合、ランタイムはイメージを読み取り、base64 に自動的に変換します
自動サイズ変更ランタイムは、モデル固有の制限を超えるイメージのサイズを自動的に変更または品質を下げます
ビジョン機能モデルには、イメージを処理するための capabilities.supports.vision = true が必要です

クイック スタート - 添付ファイル

添付ファイルの種類を使用して、画像ファイルを任意のメッセージに添付します。 パスは、ディスク上のイメージへの絶対パスである必要があります。

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

クイック スタート — Blob 添付ファイル

既にメモリ内に画像データがある場合 (アプリによってキャプチャされたスクリーンショットや API からフェッチされたイメージなど)、BLOB 添付ファイルを使用して、ディスクに書き込まずに直接送信します。

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

サポートされるフォーマット

サポートされている画像形式には、JPG、PNG、GIF、およびその他の一般的な画像の種類があります。 添付ファイルの場合、ランタイムはディスクからイメージを読み取り、必要に応じて変換します。 BLOB 添付ファイルの場合は、base64 データと MIME の種類を直接指定します。 最も広くサポートされている形式のため、最適な結果を得るには PNG または JPEG を使用します。

モデルの capabilities.limits.vision.supported_media_types フィールドには、受け入れられる正確な MIME の種類が一覧表示されます。

自動処理

ランタイムは、モデルの制約内に収まるようにイメージを自動的に処理します。 手動によるサイズ変更は必要ありません。

  • モデルの寸法またはサイズの制限を超える画像は、自動的にサイズ変更 (縦横比を維持) または品質が低下します。
  • 処理後に制限内にイメージを取り込むことができない場合、イメージはスキップされ、LLM に送信されません。
  • モデルの capabilities.limits.vision.max_prompt_image_size フィールドは、最大イメージ サイズをバイト単位で示します。

これらの制限は、実行時にモデル機能オブジェクトを使用して確認できます。 最適なエクスペリエンスを実現するために、合理的なサイズの PNG または JPEG 画像を使用します。

ビジョン モデルの機能

すべてのモデルがビジョンをサポートしているわけではありません。 画像を送信する前に、モデルの機能を確認します。

機能フィールド

フィールドタイプDescription
capabilities.supports.visionbooleanモデルが画像入力を処理できるかどうか
capabilities.limits.vision.supported_media_typesstring[]モデルが受け入れる MIME の種類 (例: ["image/png", "image/jpeg"])
capabilities.limits.vision.max_prompt_imagesnumberプロンプトあたりのイメージの最大数
capabilities.limits.vision.max_prompt_image_sizenumber最大イメージ サイズ (バイト単位)

ビジョンの制限の種類

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

画像の結果を受け取る

ツールが画像 (スクリーンショットや生成されたグラフなど) を返すと、結果には base64 でエンコードされたデータを含む "image" コンテンツ ブロックが含まれます。

フィールドタイプDescription
type"image"コンテンツブロックタイプ判別子
datastringBase64 でエンコードされた画像データ
mimeTypestringMIME の種類 (例: "image/png")

これらのイメージ ブロックは、tool.execution_complete イベント結果に現れます。 イベントのライフサイクル全体については、 ストリーミング セッション イベント ガイドを参照してください。

ヒントと制限事項

Tip詳細情報
PNG または JPEG を直接使用する変換のオーバーヘッドを回避します。これらは LLM as-is に送信されます
画像のサイズを適度に維持する大きな画像は品質が低下する可能性があり、重要な詳細が失われる可能性があります
添付ファイルに絶対パスを使用するランタイムはディスクからファイルを読み取ります。相対パスが正しく解決されない可能性がある
インメモリ データに BLOB 添付ファイルを使用するbase64 データ (スクリーンショット、API 応答など) が既にある場合、BLOB は不要なディスク I/O を回避します
最初に視覚サポートを確認する非ビジョン モデルに画像を送信すると、視覚的な理解なしにトークンが無駄になります
複数のイメージがサポートされていますモデルの max_prompt_images 制限まで、複数の添付ファイルを 1 つのメッセージに添付する
SVG はサポートされていませんSVG ファイルはテキストベースであり、画像処理から除外されます

こちらも参照ください