Render a snippet
Turns code into an image, styled with one of your organization’s style presets. You get the image bytes back, or a link to the image. You can also save the code as a snippet in your library.
POST /api/v1/rendersAuthorization
Section titled “Authorization”| Requirement | Value |
|---|---|
| Header | Authorization: Bearer <token> |
| Scope | render_snippets |
Scope, when the body has save | write_snippets as well |
Example request
Section titled “Example request”curl https://api.prettycode.dev/v1/renders \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: image/png, application/json" \ -d '{ "preset": "Blog", "tabs": [ {"filename": "app.ts", "content": "const answer = 42;\nconsole.log(answer);\n", "highlighted_lines": "2"} ] }' \ --output app.ts.pngAsk for a link instead, and save the snippet in a folder with two tags:
curl https://api.prettycode.dev/v1/renders \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "preset": "Blog", "tabs": [ {"filename": "a.ts", "content": "export const a = 1;\n"}, {"filename": "b.ts", "content": "import {a} from \"./a\";\n", "language": "typescript"} ], "active_tab": "b.ts", "format": "webp", "size": {"aspect_ratio": "16:9"}, "response": "json", "save": {"folder": "Docs", "tags": ["typescript", "examples"]} }'Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
preset | string | Yes | The exact name of a style preset in your organization’s default workspace. The preset sets the theme, font, window and background. List them with GET /v1/presets. |
tabs | array | Yes | The snippet’s tabs, 1 to 10. |
tabs[].filename | string | Yes | The tab’s filename. Each tab needs its own. |
tabs[].content | string | Yes | The code. At most 30 000 characters. |
tabs[].language | string | null | No | The language to highlight it as, such as typescript. Leave it out to detect it from the code. |
tabs[].highlighted_lines | string | No | Lines to highlight, as a list like "1,3-5", at most 1000 characters. Use the line numbers the image shows: with line_numbers.start at 120, the first line is 120. |
tabs[].line_numbers.visible | boolean | No | Show line numbers. Default true. |
tabs[].line_numbers.start | integer | No | The number of the first line. Default 1. |
active_tab | string | integer | No | The tab to draw: its filename, or its position counted from 0. Default 0. |
format | string | No | png (default), svg, jpeg or webp. |
size | object | No | One of the three shapes below. Default: the code’s own size at scale 2. |
response | string | No | image (default) answers the image itself; json answers a link to it. |
save | object | No | Save the tabs as a snippet in your library, with the preset’s style. Needs the write_snippets scope. |
save.folder | string | No | The folder to save it in, by exact name. A folder that doesn’t exist yet is created in the default workspace. |
save.tags | string[] | No | Tags to add, by exact name. Tags that don’t exist yet are created. |
| Shape | Image |
|---|---|
{"scale": 2} | The code’s own size, times 1, 2 or 4. |
{"width": 1200, "height": 630} | Exactly this many pixels. The window is scaled to fit and the background fills the rest. Don’t send scale with it. |
{"aspect_ratio": "16:9", "scale": 2} | The code’s own size widened or heightened to the ratio: 1:1, 4:3, 16:9, 4:5, 9:16 or 1.91:1. scale is optional, default 2. |
The image’s longest side can be at most 8000 pixels, and the drawn tab at most 200 lines.
Response
Section titled “Response”response: "image"
Section titled “response: "image"”200 OK with the image itself. The Content-Type header is the image’s type, such as image/png.
| Header | Description |
|---|---|
X-Image-Width | The image’s width in pixels. |
X-Image-Height | The image’s height in pixels. |
X-Alt-Text | A text description of the image, URL-encoded. Decode it before use, for example with decodeURIComponent. |
X-Snippet-Id | The saved snippet’s ID. Only sent when the request had save. |
response: "json"
Section titled “response: "json"”200 OK
{ "data": { "url": "https://api.prettycode.dev/renders/01JABCDEF0123456789ABCDEFG?expires=1763550000&signature=…", "expires_at": "2026-11-19T12:00:00+00:00", "width": 1856, "height": 1044, "format": "webp", "alt_text": "TypeScript code from b.ts, 1 line: import {a} from \"./a\";", "snippet_id": "01JABCDEF0123456789ABCDEFH" }}Fields
Section titled “Fields”| Field | Type | Description |
|---|---|---|
url | string | A link to the image. Anyone with the link can open it until it expires. Add &download=1 to download it as a file. |
expires_at | string | When the link stops working (ISO 8601), one hour after the request. |
width | integer | The image’s width in pixels. |
height | integer | The image’s height in pixels. |
format | string | png, svg, jpeg or webp. |
alt_text | string | A text description of the image. |
snippet_id | string | null | The saved snippet’s ID, or null when the request had no save. |
Errors
Section titled “Errors”Every error answers JSON with a message.
| Status | When |
|---|---|
401 Unauthorized | Missing or invalid token. |
403 Forbidden | The organization’s plan doesn’t qualify, the token lacks the render_snippets scope, or the body has save and the token lacks the write_snippets scope. Nothing is drawn or saved. |
422 Unprocessable Entity | The request can’t be drawn. The message says why and names what is wrong: a preset, tab, line, theme, font, language, format, size or aspect ratio that doesn’t exist, a list of highlighted lines that isn’t like 1,3-5, a tab over 200 lines or 30 000 characters, more than 10 tabs, or an image over 8000 pixels on a side. Fields with the wrong shape are listed under errors. |
429 Too Many Requests | Your organization sent too many requests this minute — wait the seconds in the Retry-After header. Renders also have their own limit: 60 a minute for your whole organization, shared by all its tokens. |
503 Service Unavailable | Images can’t be made right now. Try again in a moment. |
A preset that doesn’t exist answers with its own code, and the name you sent:
{ "message": "There is no style preset named \"Blgo\".", "code": "preset_not_found", "preset": "Blgo"}An image over the size limit answers with code: "image_too_large" and the size it would have had:
{ "message": "The image would be 41160 × 1044 pixels. The longest side can be at most 8000. Use a smaller scale or size.", "code": "image_too_large", "width": 41160, "height": 1044, "max_side": 8000}