# 画像入力

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

<!-- markdownlint-disable GHD046 GHD005 -->

<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->

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

## Overview

![図: 説明されたプロセスを示すシーケンス図。](/assets/images/help/copilot/copilot-sdk/features-image-input-diagram-0.png)

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

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

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

<div class="ghd-codetabs">
<div class="ghd-codetab" data-lang="typescript" data-label="TypeScript"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">TypeScript</div>

```typescript
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();

const session = await client.createSession({
    model: "gpt-5.4",
    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",
        },
    ],
});
```

</div>

<div class="ghd-codetab" data-lang="python" data-label="Python"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Python</div>

```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-5.4",
)

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

</div>

<div class="ghd-codetab" data-lang="go" data-label="Go"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Go</div>

```golang
ctx := context.Background()
client := copilot.NewClient(nil)
client.Start(ctx)

session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
    Model: "gpt-5.4",
    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.AttachmentFile{
            DisplayName: "screenshot.png",
            Path:        path,
        },
    },
})
```

</div>

<div class="ghd-codetab" data-lang="dotnet" data-label=".NET"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">.NET</div>

```csharp
using GitHub.Copilot;
using GitHub.Copilot.Rpc;

await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(new SessionConfig
{
    Model = "gpt-5.4",
    OnPermissionRequest = (req, inv) =>
        Task.FromResult(PermissionDecision.ApproveOnce()),
});

await session.SendAsync(new MessageOptions
{
    Prompt = "Describe what you see in this image",
    Attachments = new List<Attachment>
    {
        new AttachmentFile
        {
            Path = "/absolute/path/to/screenshot.png",
            DisplayName = "screenshot.png",
        },
    },
});
```

</div>

<div class="ghd-codetab" data-lang="java" data-label="Java"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Java</div>

```java
import com.github.copilot.CopilotClient;
import com.github.copilot.rpc.*;
import java.util.List;

try (var client = new CopilotClient()) {
    client.start().get();

    var session = client.createSession(
        new SessionConfig()
            .setModel("gpt-5.4")
            .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();
}
```

</div>

</div>

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

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

<div class="ghd-codetabs">
<div class="ghd-codetab" data-lang="typescript" data-label="TypeScript"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">TypeScript</div>

```typescript
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();

const session = await client.createSession({
    model: "gpt-5.4",
    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",
        },
    ],
});
```

</div>

<div class="ghd-codetab" data-lang="python" data-label="Python"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Python</div>

```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-5.4",
)

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

</div>

<div class="ghd-codetab" data-lang="go" data-label="Go"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Go</div>

```golang
mimeType := "image/png"
displayName := "screenshot.png"
session.Send(ctx, copilot.MessageOptions{
    Prompt: "Describe what you see in this image",
    Attachments: []copilot.Attachment{
        &copilot.AttachmentBlob{
            Data:        &base64ImageData, // base64-encoded string
            MIMEType:    mimeType,
            DisplayName: &displayName,
        },
    },
})
```

</div>

<div class="ghd-codetab" data-lang="dotnet" data-label=".NET"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">.NET</div>

```csharp
await session.SendAsync(new MessageOptions
{
    Prompt = "Describe what you see in this image",
    Attachments = new List<Attachment>
    {
        new AttachmentBlob
        {
            Data = base64ImageData,
            MimeType = "image/png",
            DisplayName = "screenshot.png",
        },
    },
});
```

</div>

<div class="ghd-codetab" data-lang="java" data-label="Java"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Java</div>

```java
import com.github.copilot.CopilotClient;
import com.github.copilot.rpc.*;
import java.util.List;

try (var client = new CopilotClient()) {
    client.start().get();

    var session = client.createSession(
        new SessionConfig()
            .setModel("gpt-5.4")
            .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();
}
```

</div>

</div>

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

サポートされている画像形式には、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.vision`                     | `boolean`  | モデルが画像入力を処理できるかどうか                                    |
| `capabilities.limits.vision.supported_media_types` | `string[]` | モデルが受け入れる MIME の種類 (例: `["image/png", "image/jpeg"]`) |
| `capabilities.limits.vision.max_prompt_images`     | `number`   | プロンプトあたりのイメージの最大数                                     |
| `capabilities.limits.vision.max_prompt_image_size` | `number`   | 最大イメージ サイズ (バイト単位)                                    |

### ビジョンの制限の種類

```typescript
vision?: {
    supported_media_types: string[];
    max_prompt_images: number;
    max_prompt_image_size: number; // bytes
};
```

## 画像の結果を受け取る

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

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

これらのイメージ ブロックは、`tool.execution_complete` イベント結果に現れます。 イベントのライフサイクル全体については、 [ストリーミング セッション イベント](/ja/copilot/how-tos/copilot-sdk/features/streaming-events) ガイドを参照してください。

## ヒントと制限事項

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

## こちらも参照ください

* [ストリーミング セッション イベント](/ja/copilot/how-tos/copilot-sdk/features/streaming-events): ツールの結果コンテンツ ブロックを含むイベント ライフサイクル
* [ステアリングとキューイング](/ja/copilot/how-tos/copilot-sdk/features/steering-and-queueing): 添付ファイルを含むフォローアップ メッセージの送信