# 이미지 입력

Copilot 세션에 이미지를 첨부 파일로 보냅니다. 이미지를 연결하는 방법에는 두 가지가 있습니다.

<!-- 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)

| Concept                                                                          | 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 이미지를 사용합니다.

## 비전 모델 기능

모든 모델이 비전을 지원하는 것은 아닙니다. 이미지를 보내기 전에 모델의 기능을 확인합니다.

### 기능 필드

| Field                                              | Type       | 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"` 됩니다.

| Field      | Type      | Description               |
| ---------- | --------- | ------------------------- |
| `type`     | `"image"` | 콘텐츠 블록 형식 판별자             |
| `data`     | `string`  | Base64로 인코딩된 이미지 데이터      |
| `mimeType` | `string`  | MIME 형식(예: `"image/png"`) |

이러한 이미지 블록은 `tool.execution_complete` 이벤트 결과에 표시됩니다. 전체 이벤트 수명 주기는 [스트리밍 세션 이벤트](/ko/copilot/how-tos/copilot-sdk/features/streaming-events) 가이드를 참조하세요.

## 팁 및 제한 사항

| Tip                          | Details                                                          |
| ---------------------------- | ---------------------------------------------------------------- |
| **PNG 또는 JPEG 직접 사용**        | 변환 오버헤드를 방지합니다. 이는 LLM as-is 전송됩니다.                              |
| **이미지 크기를 합리적으로 유지**         | 큰 이미지는 품질이 저하되어 중요한 세부 정보를 잃을 수 있습니다.                            |
| **파일 첨부 파일에 절대 경로 사용**       | 런타임은 디스크에서 파일을 읽습니다. 상대 경로가 올바르게 확인되지 않을 수 있습니다.                 |
| **메모리 내 데이터에 Blob 첨부 파일 사용** | base64 데이터(예: 스크린샷, API 응답)가 이미 있는 경우 Blob은 불필요한 디스크 I/O를 방지합니다. |
| **먼저 비전 지원 확인**              | 비전이 아닌 모델로 이미지를 보내면 시각적 이해 없이 토큰이 낭비됩니다.                         |
| **여러 이미지가 지원됩니다.**           | 한 메시지에 여러 첨부 파일을 모델의 `max_prompt_images` 제한까지 첨부합니다.             |
| **SVG는 지원되지 않습니다.**          | SVG 파일은 텍스트 기반이며 이미지 처리에서 제외됩니다.                                 |

## 참고하십시오

* [스트리밍 세션 이벤트](/ko/copilot/how-tos/copilot-sdk/features/streaming-events): 도구 결과 콘텐츠 블록을 포함한 이벤트 수명 주기
* [스티어링 및 대기열 지정](/ko/copilot/how-tos/copilot-sdk/features/steering-and-queueing): 첨부 파일이 포함된 후속 메시지 보내기