{"meta":{"title":"이미지 입력","intro":"Copilot 세션에 이미지를 첨부 파일로 보냅니다. 이미지를 연결하는 방법에는 두 가지가 있습니다.","product":"GitHub Copilot","breadcrumbs":[{"href":"/ko/copilot","title":"GitHub Copilot"},{"href":"/ko/copilot/how-tos","title":"방법"},{"href":"/ko/copilot/how-tos/copilot-sdk","title":"코필로트 SDK"},{"href":"/ko/copilot/how-tos/copilot-sdk/features","title":"기능"},{"href":"/ko/copilot/how-tos/copilot-sdk/features/image-input","title":"이미지 입력"}],"documentType":"article"},"body":"# 이미지 입력\n\nCopilot 세션에 이미지를 첨부 파일로 보냅니다. 이미지를 연결하는 방법에는 두 가지가 있습니다.\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n* **파일 첨부 파일** (`type: \"file\"`): 절대 경로를 제공하고, 런타임은 디스크에서 파일을 읽고, base64로 변환하고, LLM으로 보냅니다.\n* **Blob 첨부 파일** (`type: \"blob\"`): base64로 인코딩된 데이터를 직접 제공합니다. 이미지가 이미 메모리에 있을 때 유용합니다(예: 스크린샷, 생성된 이미지 또는 API의 데이터).\n\n## Overview\n\n![다이어그램: 설명된 프로세스를 보여 주는 시퀀스 다이어그램](/assets/images/help/copilot/copilot-sdk/features-image-input-diagram-0.png)\n\n| Concept                                                                          | Description                                                    |\n| -------------------------------------------------------------------------------- | -------------------------------------------------------------- |\n| **파일 첨부**                                                                        | 디스크의 이미지에 대한 `type: \"file\"` 및 절대 `path`가 있는 첨부 파일입니다.          |\n| **Blob 파일 첨부**                                                                   |                                                                |\n| `type: \"blob\"`, base64로 인코딩된 `data` 및 `mimeType`이 있는 첨부 파일입니다. 디스크 I/O가 필요 없습니다. |                                                                |\n| **자동 인코딩**                                                                       | 파일 첨부 파일의 경우 런타임은 이미지를 읽고 자동으로 base64로 변환합니다.                  |\n| **자동 크기 조정**                                                                     | 런타임은 모델별 제한을 초과하는 이미지의 크기를 자동으로 조정하거나 품질을 줄입니다.                |\n| **비전 기능**                                                                        | 모델은 이미지를 처리하기 위해 `capabilities.supports.vision = true`가 필요합니다. |\n\n## 빠른 시작 - 파일 첨부\n\n파일 첨부 파일 형식을 사용하여 모든 메시지에 이미지 파일을 첨부합니다. 경로는 디스크의 이미지에 대한 절대 경로여야 합니다.\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"typescript\" data-label=\"TypeScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">TypeScript</div>\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient();\nawait client.start();\n\nconst session = await client.createSession({\n    model: \"gpt-5.4\",\n    onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n\nawait session.send({\n    prompt: \"Describe what you see in this image\",\n    attachments: [\n        {\n            type: \"file\",\n            path: \"/absolute/path/to/screenshot.png\",\n        },\n    ],\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\nfrom copilot import CopilotClient, PermissionDecisionApproveOnce\n\nclient = CopilotClient()\nawait client.start()\n\nsession = await client.create_session(\n    on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),\n    model=\"gpt-5.4\",\n)\n\nawait session.send(\n    \"Describe what you see in this image\",\n    attachments=[\n        {\n            \"type\": \"file\",\n            \"path\": \"/absolute/path/to/screenshot.png\",\n        },\n    ],\n)\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n```golang\nctx := context.Background()\nclient := copilot.NewClient(nil)\nclient.Start(ctx)\n\nsession, _ := client.CreateSession(ctx, &copilot.SessionConfig{\n    Model: \"gpt-5.4\",\n    OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {\n        return &rpc.PermissionDecisionApproveOnce{}, nil\n    },\n})\n\npath := \"/absolute/path/to/screenshot.png\"\nsession.Send(ctx, copilot.MessageOptions{\n    Prompt: \"Describe what you see in this image\",\n    Attachments: []copilot.Attachment{\n        &copilot.AttachmentFile{\n            DisplayName: \"screenshot.png\",\n            Path:        path,\n        },\n    },\n})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n```csharp\nusing GitHub.Copilot;\nusing GitHub.Copilot.Rpc;\n\nawait using var client = new CopilotClient();\nawait using var session = await client.CreateSessionAsync(new SessionConfig\n{\n    Model = \"gpt-5.4\",\n    OnPermissionRequest = (req, inv) =>\n        Task.FromResult(PermissionDecision.ApproveOnce()),\n});\n\nawait session.SendAsync(new MessageOptions\n{\n    Prompt = \"Describe what you see in this image\",\n    Attachments = new List<Attachment>\n    {\n        new AttachmentFile\n        {\n            Path = \"/absolute/path/to/screenshot.png\",\n            DisplayName = \"screenshot.png\",\n        },\n    },\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n```java\nimport com.github.copilot.CopilotClient;\nimport com.github.copilot.rpc.*;\nimport java.util.List;\n\ntry (var client = new CopilotClient()) {\n    client.start().get();\n\n    var session = client.createSession(\n        new SessionConfig()\n            .setModel(\"gpt-5.4\")\n            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)\n    ).get();\n\n    session.send(new MessageOptions()\n        .setPrompt(\"Describe what you see in this image\")\n        .setAttachments(List.of(\n            new Attachment(\"file\", \"/absolute/path/to/screenshot.png\", \"screenshot.png\")\n        ))\n    ).get();\n}\n```\n\n</div>\n\n</div>\n\n## 빠른 시작 - Blob 첨부\n\n이미 메모리에 이미지 데이터가 있는 경우(예: 앱에서 캡처한 스크린샷 또는 API에서 가져온 이미지) Blob 첨부 파일을 사용하여 디스크에 쓰지 않고 직접 보냅니다.\n\n<div class=\"ghd-codetabs\">\n<div class=\"ghd-codetab\" data-lang=\"typescript\" data-label=\"TypeScript\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">TypeScript</div>\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient();\nawait client.start();\n\nconst session = await client.createSession({\n    model: \"gpt-5.4\",\n    onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n\nconst base64ImageData = \"...\"; // your base64-encoded image\nawait session.send({\n    prompt: \"Describe what you see in this image\",\n    attachments: [\n        {\n            type: \"blob\",\n            data: base64ImageData,\n            mimeType: \"image/png\",\n            displayName: \"screenshot.png\",\n        },\n    ],\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"python\" data-label=\"Python\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Python</div>\n\n```python\nfrom copilot import CopilotClient, PermissionDecisionApproveOnce\n\nclient = CopilotClient()\nawait client.start()\n\nsession = await client.create_session(\n    on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),\n    model=\"gpt-5.4\",\n)\n\nbase64_image_data = \"...\"  # your base64-encoded image\nawait session.send(\n    \"Describe what you see in this image\",\n    attachments=[\n        {\n            \"type\": \"blob\",\n            \"data\": base64_image_data,\n            \"mimeType\": \"image/png\",\n            \"displayName\": \"screenshot.png\",\n        },\n    ],\n)\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"go\" data-label=\"Go\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Go</div>\n\n```golang\nmimeType := \"image/png\"\ndisplayName := \"screenshot.png\"\nsession.Send(ctx, copilot.MessageOptions{\n    Prompt: \"Describe what you see in this image\",\n    Attachments: []copilot.Attachment{\n        &copilot.AttachmentBlob{\n            Data:        &base64ImageData, // base64-encoded string\n            MIMEType:    mimeType,\n            DisplayName: &displayName,\n        },\n    },\n})\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"dotnet\" data-label=\".NET\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">.NET</div>\n\n```csharp\nawait session.SendAsync(new MessageOptions\n{\n    Prompt = \"Describe what you see in this image\",\n    Attachments = new List<Attachment>\n    {\n        new AttachmentBlob\n        {\n            Data = base64ImageData,\n            MimeType = \"image/png\",\n            DisplayName = \"screenshot.png\",\n        },\n    },\n});\n```\n\n</div>\n\n<div class=\"ghd-codetab\" data-lang=\"java\" data-label=\"Java\"><div class=\"ghd-codetab-fallback-label\" role=\"heading\" aria-level=\"3\">Java</div>\n\n```java\nimport com.github.copilot.CopilotClient;\nimport com.github.copilot.rpc.*;\nimport java.util.List;\n\ntry (var client = new CopilotClient()) {\n    client.start().get();\n\n    var session = client.createSession(\n        new SessionConfig()\n            .setModel(\"gpt-5.4\")\n            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)\n    ).get();\n\n    var base64ImageData = \"...\"; // your base64-encoded image\n    session.send(new MessageOptions()\n        .setPrompt(\"Describe what you see in this image\")\n        .setAttachments(List.of(\n            new BlobAttachment()\n                .setData(base64ImageData)\n                .setMimeType(\"image/png\")\n                .setDisplayName(\"screenshot.png\")\n        ))\n    ).get();\n}\n```\n\n</div>\n\n</div>\n\n## 지원되는 형식\n\n지원되는 이미지 형식에는 JPG, PNG, GIF 및 기타 일반적인 이미지 형식이 포함됩니다. 파일 첨부 파일의 경우 런타임은 디스크에서 이미지를 읽고 필요에 따라 변환합니다. Blob 첨부 파일의 경우 base64 데이터 및 MIME 형식을 직접 제공합니다. 가장 널리 지원되는 형식이므로 최상의 결과를 위해 PNG 또는 JPEG를 사용합니다.\n\n모델의 `capabilities.limits.vision.supported_media_types` 필드에는 모델에서 허용하는 정확한 MIME 형식이 나열됩니다.\n\n## 자동 처리\n\n런타임은 모델의 제약 조건에 맞게 이미지를 자동으로 처리합니다. 수동 크기 조정은 필요하지 않습니다.\n\n* 모델의 차원 또는 크기 제한을 초과하는 이미지는 자동으로 크기 조정(가로 세로 비율 유지) 또는 품질 저하됩니다.\n* 이미지를 처리한 후 제한 내에서 가져올 수 없는 경우 건너뛰고 LLM으로 전송되지 않습니다.\n* 모델의 `capabilities.limits.vision.max_prompt_image_size` 필드는 최대 이미지 크기(바이트)를 나타냅니다.\n\n모델 기능 개체를 통해 런타임에 이러한 제한을 확인할 수 있습니다. 최상의 환경을 위해 합리적인 크기의 PNG 또는 JPEG 이미지를 사용합니다.\n\n## 비전 모델 기능\n\n모든 모델이 비전을 지원하는 것은 아닙니다. 이미지를 보내기 전에 모델의 기능을 확인합니다.\n\n### 기능 필드\n\n| Field                                              | Type       | Description                                       |\n| -------------------------------------------------- | ---------- | ------------------------------------------------- |\n| `capabilities.supports.vision`                     | `boolean`  | 모델이 이미지 입력을 처리할 수 있는지 여부                          |\n| `capabilities.limits.vision.supported_media_types` | `string[]` | 모델이 허용하는 MIME 형식(예: `[\"image/png\", \"image/jpeg\"]` |\n| `capabilities.limits.vision.max_prompt_images`     | `number`   | 프롬프트당 최대 이미지 수                                    |\n| `capabilities.limits.vision.max_prompt_image_size` | `number`   | 최대 이미지 크기(바이트)                                    |\n\n### 비전 제한 유형\n\n```typescript\nvision?: {\n    supported_media_types: string[];\n    max_prompt_images: number;\n    max_prompt_image_size: number; // bytes\n};\n```\n\n## 이미지 결과 받기\n\n도구가 이미지를 반환하는 경우(예: 스크린샷 또는 생성된 차트) 결과에는 base64로 인코딩된 데이터가 포함된 콘텐츠 블록이 포함 `\"image\"` 됩니다.\n\n| Field      | Type      | Description               |\n| ---------- | --------- | ------------------------- |\n| `type`     | `\"image\"` | 콘텐츠 블록 형식 판별자             |\n| `data`     | `string`  | Base64로 인코딩된 이미지 데이터      |\n| `mimeType` | `string`  | MIME 형식(예: `\"image/png\"`) |\n\n이러한 이미지 블록은 `tool.execution_complete` 이벤트 결과에 표시됩니다. 전체 이벤트 수명 주기는 [스트리밍 세션 이벤트](/ko/copilot/how-tos/copilot-sdk/features/streaming-events) 가이드를 참조하세요.\n\n## 팁 및 제한 사항\n\n| Tip                          | Details                                                          |\n| ---------------------------- | ---------------------------------------------------------------- |\n| **PNG 또는 JPEG 직접 사용**        | 변환 오버헤드를 방지합니다. 이는 LLM as-is 전송됩니다.                              |\n| **이미지 크기를 합리적으로 유지**         | 큰 이미지는 품질이 저하되어 중요한 세부 정보를 잃을 수 있습니다.                            |\n| **파일 첨부 파일에 절대 경로 사용**       | 런타임은 디스크에서 파일을 읽습니다. 상대 경로가 올바르게 확인되지 않을 수 있습니다.                 |\n| **메모리 내 데이터에 Blob 첨부 파일 사용** | base64 데이터(예: 스크린샷, API 응답)가 이미 있는 경우 Blob은 불필요한 디스크 I/O를 방지합니다. |\n| **먼저 비전 지원 확인**              | 비전이 아닌 모델로 이미지를 보내면 시각적 이해 없이 토큰이 낭비됩니다.                         |\n| **여러 이미지가 지원됩니다.**           | 한 메시지에 여러 첨부 파일을 모델의 `max_prompt_images` 제한까지 첨부합니다.             |\n| **SVG는 지원되지 않습니다.**          | SVG 파일은 텍스트 기반이며 이미지 처리에서 제외됩니다.                                 |\n\n## 참고하십시오\n\n* [스트리밍 세션 이벤트](/ko/copilot/how-tos/copilot-sdk/features/streaming-events): 도구 결과 콘텐츠 블록을 포함한 이벤트 수명 주기\n* [스티어링 및 대기열 지정](/ko/copilot/how-tos/copilot-sdk/features/steering-and-queueing): 첨부 파일이 포함된 후속 메시지 보내기"}