---
title: "Rendering Images"
canonical_url: https://docs.zvid.io/docs/rendering-images/
source: docs/rendering-images.md
content_revision: 6338386a1dd87e4a
---
# Rendering Images
Image projects use Zvid's composition model to render a **PNG, JPG, or WebP**.
Set `type: "image"`, use static `IMAGE`, `TEXT`/HTML, or `SVG` visuals, and
omit video-only timing, audio, and scene fields. Positioning, text styling,
filters, and safe `customCode` remain available.
## First image
Create an [API key](https://docs.zvid.io/docs/authentication/) and use this complete request.
It costs **1 credit**. To validate it for free first, send the same body to
`POST /api/render/validate/api-key` instead; see
[Validate and estimate](https://docs.zvid.io/docs/validate-and-estimate/).
```bash
curl -X POST https://api.zvid.io/api/render/image/api-key \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"payload": {
"type": "image",
"name": "hello-image",
"width": 1200,
"height": 675,
"outputFormat": "png",
"backgroundColor": "#ffffff",
"visuals": [{
"type": "TEXT",
"text": "Hello, Zvid!",
"position": "center-center",
"style": { "fontFamily": "Poppins", "fontSize": 72, "color": "#111111" }
}]
}
}'
```
You can submit an image payload to the regular `/api/render/api-key` endpoint
too. The `/api/render/image/*` endpoints set `type: "image"` on an inline
payload; when using a stored template, that template must already be an image
project. `overrides` cannot change a template's type.
## Image-Specific Fields
| Field | Type | Default | Notes |
| -------------- | ---------------------------------- | --------------- | ---------------------------------------------------------------------------- |
| `type` | `"image"` | `"video"` | Switches the render to image output. |
| `outputFormat` | `png` \| `jpg` \| `jpeg` \| `webp` | `png` | Video formats are rejected for image renders. |
| `transparent` | `boolean` | `false` | Transparent background. PNG/WebP only — rejected with `jpg`. |
| `quality` | `1`–`100` | encoder default | JPG/WebP compression quality — rejected with `png`. |
| `snapshotTime` | `number` (seconds, 0–3600) | start | Which moment of animated content (e.g. a `customCode` animation) to capture. |
## Converting a video composition
1. Set `type: "image"` and choose an image `outputFormat`.
2. Remove root `duration`, `durationMode`, `frameRate`, `audios`, `scenes`,
`subtitle`, and `thumbnail`. Move the desired static scene visuals into
the root `visuals` array if necessary.
3. Replace `VIDEO` and `GIF` elements with static assets; these types are
rejected in image projects.
4. Remove element `enterBegin`, `enterEnd`, `exitBegin`, `exitEnd`,
`videoBegin`, `videoEnd`, `videoDuration`, `transition`, `transitionId`,
and `transitionDuration`. Image elements are always visible.
5. Run [hosted validation](https://docs.zvid.io/docs/validate-and-estimate/) before rendering.
`snapshotTime` chooses a moment in time-based HTML/custom-code content. It
does not make video/GIF elements valid or provide video-frame extraction.
Use PNG or WebP for transparency; JPEG rejects `transparent: true`.
## Examples
### A social graphic
```json
{
"name": "docs-img-render-basic",
"type": "image",
"width": 1200,
"height": 675,
"outputFormat": "png",
"backgroundColor": "#140b2e",
"visuals": [
{
"type": "IMAGE",
"src": "https://cdn.pixabay.com/photo/2024/10/02/18/24/leaf-9091894_1280.jpg",
"width": 1200,
"height": 675,
"position": "center-center",
"resize": "cover",
"filter": {
"brightness": -20
}
},
{
"type": "TEXT",
"html": "“Ship visuals from an API.”
",
"position": "center-center",
"customCode": {
"css": ".q { color: #ffffff; font-family: Montserrat; font-size: 64px; font-weight: 800; text-shadow: 0 4px 24px rgba(0,0,0,0.6); }"
}
}
]
}
```
1200×675 PNG rendered by Zvid
[View image](https://cdn.zvid.io/library/docs/img-render-basic.png)
### Transparent sticker (PNG with alpha)
```json
{
"name": "docs-img-render-transparent",
"type": "image",
"width": 800,
"height": 600,
"outputFormat": "png",
"transparent": true,
"visuals": [
{
"type": "TEXT",
"html": "NEW DROP
",
"position": "center-center",
"customCode": {
"css": ".sticker { color: #ffffff; font-family: Poppins; font-size: 72px; font-weight: 800; padding: 28px 56px; background: linear-gradient(135deg, #7c3aed, #d946ef); border-radius: 999px; transform: rotate(-6deg); box-shadow: 0 12px 40px rgba(124,58,237,0.5); }"
}
}
]
}
```
transparent: true — drop it on any background
[View image](https://cdn.zvid.io/library/docs/img-render-transparent.png)
> **This site's social card is a Zvid render**
The Open Graph image for docs.zvid.io is generated by this exact feature — a
1200×630 `type: "image"` render.
## Credits
Image renders cost **1 credit per image**, including bulk renders —
resolution-independent. A single image render costs 1 credit; a
[bulk render](https://docs.zvid.io/docs/automation/bulk-rendering/) of 25 images costs 25 credits.
## Response
The submit/poll flow is identical to video — see the
[Quick Start](https://docs.zvid.io/docs/quick-start/). A completed job's output points at the image
file; there is no separate thumbnail. Read `result.url` when `result` is an
object, or use `result` directly when stored history returns a URL string.
See [Render lifecycle](https://docs.zvid.io/docs/operations/render-lifecycle/) for both response shapes.
## In the Editor
The editor has a first-class image mode: **New → Image** hides the time-domain
tools (timeline, audio, scenes, subtitles) and the render dialog offers format,
quality, and transparency options. See [Rendering & export](https://docs.zvid.io/docs/editor/export/).
## Related
- [Quick Start](https://docs.zvid.io/docs/quick-start/)
- [Bulk rendering](https://docs.zvid.io/docs/automation/bulk-rendering/)
- [Templates](https://docs.zvid.io/docs/templates/template-basics/) — data-driven image batches