# image


Convert images, extract frames from video

```bash
ittybit image \
  -i photo.png \
  -o photo.webp
```

Converts between image formats, resizes, or extracts a frame from video. Use this to generate thumbnails, convert to modern formats like WebP, or pull poster frames for video players.

## Options

| Flag           | Values                                               | Default       |
| -------------- | ---------------------------------------------------- | ------------- |
| `--format`     | `jpeg` · `png` · `webp` · `avif`                     | per input     |
| `--quality`    | `very_low` · `low` · `medium` · `high` · `very_high` | auto          |
| `--width`      | pixels or `"50%"`                                    | same as input |
| `--height`     | pixels or `"50%"`                                    | same as input |
| `--fit`        | `contain` · `cover` · `fill`                         | —             |
| `--background` | hex color (e.g. `#000000`)                           | —             |
| `--start`      | seconds (frame extraction time)                      | 0             |

## Examples

Extract a poster frame from video:

```bash
ittybit image \
  -i video.mp4 \
  -o poster.jpg \
  --start 5
```

---

Create a thumbnail:

```bash
ittybit image \
  -i photo.jpg \
  -o thumb.jpg \
  --width 320 \
  --quality medium
```

---

Convert to WebP:

```bash
ittybit image \
  -i photo.png \
  -o photo.webp
```

---

Output to S3:

```bash
ittybit image \
  -i s3://bucket/raw/photo.png \
  -o s3://bucket/thumbs/photo.webp \
  --connection my-s3 \
  --width 640
```

## Local

Run locally using FFmpeg instead of cloud:

```bash
ittybit image \
  -i video.mp4 \
  -o poster.jpg \
  --local \
  --start 5 \
  --width 640
```

Requires FFmpeg installed. The file is processed on your machine.

## See also

- [API `POST /jobs`](/api/create-job) with `kind: "image"` — process images via HTTP
- [Extract thumbnails from video](/guides/thumbnail) — full guide with format comparison
- [`animation`](/cli/animation) — extract animated clips (GIF/WebP) from video
- [`video`](/cli/video) — transcode the full video
- [`connections`](/cli/connections) — set up S3 for input/output