Dax
108 lines
5.2 KiB
Plaintext
108 lines
5.2 KiB
Plaintext
---
|
|
title: "Attachments"
|
|
---
|
|
|
|
Attachments add local context to a prompt as text or image media. Regardless
|
|
of how a prompt is submitted, current V2 sessions make these attachment types
|
|
visible to the model:
|
|
|
|
| Input | Model receives |
|
|
| ----------------------- | -------------------------------------------------------------- |
|
|
| UTF-8 text file | The filename and decoded text |
|
|
| Directory | A non-recursive listing of its immediate files and directories |
|
|
| PNG, JPEG, GIF, or WebP | Image media |
|
|
|
|
SVG files are treated as text, not image media. PDF, AVIF, BMP, audio, video,
|
|
and other binary prompt attachments are not currently included in the model
|
|
request. A client accepting a file does not mean its contents are visible to
|
|
the model.
|
|
|
|
<Callout type="warning">
|
|
Use a model that supports image input before attaching an image. OpenCode passes supported image media to the selected
|
|
provider, but the provider and model still enforce their own formats, dimensions, file counts, and size limits. A
|
|
text-only model may reject the request.
|
|
</Callout>
|
|
|
|
## Add attachments
|
|
|
|
Desktop and web clients provide **Attach file**, paste, and drag-and-drop controls for supported text and image files. The
|
|
desktop file picker limits one selection to 20 MiB in total; the server also applies the per-attachment limit below.
|
|
|
|
Attachment controls and client-side limits depend on the interface. For programmatic submission, see the generated
|
|
[API reference](/api).
|
|
|
|
V2 prompt and command inputs represent each attachment with a `uri` and
|
|
optional `name` and `description`. Use an absolute `file:` URL for a file or
|
|
directory available to the server, or an inline `data:` URL. For a text `file:`
|
|
URL, optional positive `start` and `end` query parameters select one-based
|
|
lines:
|
|
|
|
```text
|
|
file:///home/me/project/src/server.ts?start=20&end=60
|
|
```
|
|
|
|
HTTP and HTTPS attachment URLs are not supported. OpenCode materializes each
|
|
attachment before admitting the prompt and rejects invalid URLs, unreadable
|
|
paths, non-files other than directories, and attachments over 20 MiB decoded.
|
|
The server infers the media type from the bytes. A supplied filename or data
|
|
URL media type does not make an unsupported binary format model-visible.
|
|
|
|
## Configure image processing
|
|
|
|
Configure image normalization in `opencode.json` or `opencode.jsonc`:
|
|
|
|
```jsonc title="opencode.jsonc"
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"media": {
|
|
"image": {
|
|
"auto_resize": true,
|
|
"max_width": 2000,
|
|
"max_height": 2000,
|
|
"max_base64_bytes": 5242880,
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
All fields are optional:
|
|
|
|
| Field | Default | Behavior |
|
|
| ------------------ | --------: | ----------------------------------------------------------------------------------- |
|
|
| `auto_resize` | `true` | Resize an image that exceeds any configured limit. If `false`, reject it. |
|
|
| `max_width` | `2000` | Maximum width in pixels. Must be a positive integer. |
|
|
| `max_height` | `2000` | Maximum height in pixels. Must be a positive integer. |
|
|
| `max_base64_bytes` | `5242880` | Maximum byte length of the Base64-encoded image string. Must be a positive integer. |
|
|
|
|
<Callout type="note">
|
|
These settings apply to supported image media attached directly to prompts and images produced by the built-in `read`
|
|
tool. If the image resizer is unavailable, OpenCode passes the original image through unchanged.
|
|
</Callout>
|
|
|
|
The `read` tool recognizes PNG, JPEG, GIF, and WebP by their contents and will
|
|
ingest at most 20 MiB of source image bytes. It decodes the image and compares
|
|
its width, height, and encoded Base64 length with all three configured limits.
|
|
|
|
When `auto_resize` is `true`, OpenCode preserves the aspect ratio, scales the
|
|
image down to the dimension limits, and tries progressively smaller PNG and
|
|
JPEG encodings until the Base64 limit is met. The resulting media type can
|
|
therefore change to PNG or JPEG. If no encoding fits, the tool call fails.
|
|
|
|
When `auto_resize` is `false`, exceeding any limit fails the tool call without
|
|
modifying the image. An image that cannot be decoded also fails. If the image resizer cannot be loaded, OpenCode uses the
|
|
original image instead, so these settings are processing limits rather than an upload or security boundary.
|
|
|
|
## Limits and provider behavior
|
|
|
|
- Direct prompt attachments are limited to 20 MiB decoded per item by the V2
|
|
server. Client-specific limits can be lower.
|
|
- `max_base64_bytes` counts the encoded Base64 characters in bytes, not the
|
|
decoded file size and not the complete `data:` URL.
|
|
- Text attachments are inserted into the prompt as text and do not require a
|
|
multimodal model. Large text read through the `read` tool has separate
|
|
paging and truncation limits.
|
|
- Image attachments use provider-native image input. Provider errors can still
|
|
occur when OpenCode's limits pass but the selected model's limits do not.
|
|
- PDFs and other unsupported binary prompt attachments should be converted to
|
|
text or supported images before attaching them.
|