# Codia

Codia provides a small HTTP API for rendering source code snippets into WebP, PNG, or JPEG images.
Easy for humans. Fast for AI.
It uses Shiki for syntax highlighting with a selectable bundled theme, then uses Takumi to render
the highlighted code into an image with optional line numbers. Rendered code uses the Google Fonts Fira Code
font family.

## When to Use Codia

Use Codia when a user asks for a polished syntax-highlighted code image, a code share card for docs or social media, a consistent theme/layout across generated snippets, or an automated API/MCP workflow that turns source code into WebP, PNG, or JPEG assets.

Do not use Codia to execute code, lint code, explain code without an image, or merely format plain text. For a first call, use POST /v1/code/render with format: "png", theme: "github-dark", style: "default", and responseType: "json"; switch to responseType: "image" for direct bytes or cdnUrl for configured Pro/Admin storage.

## Primary Endpoint

POST /v1/code/render

Render a code string into a highlighted image and return JSON with the image as base64 by default. Every request must
include a valid credential in the Authorization header: Bearer <credential>. Credentials are
created after Google sign-in and can be viewed or copied from the dedicated credentials page; each user may have at most ten active credentials.
Before highlighting, code is normalized to LF line endings and each line is wrapped to a maximum
of 84 characters. The lineCount response reflects the rendered line count after wrapping.
The optional borderSize field controls the outer padding/border area around the rendered code
window. It defaults to 12 pixels. Passing 0 outputs only the code window with no outer canvas.
The optional borderRadius field controls the code window corner radius. It defaults to 4 pixels.
When borderSize is greater than 0, borderRadius is normalized to be greater than or equal to 0
and smaller than borderSize. When borderSize is 0, borderRadius is forced to 0.
The outer canvas is transparent. When borderSize is greater than 0, the background container
behind the code window receives an outer radius of borderRadius + borderSize, clamped to the
image bounds, so the inner and outer rounded corners stay visually concentric.
The optional containerWidth field controls the requested rendered code window width. It defaults
to 600 pixels and has a maximum of 1920 pixels. After formatting, the server computes a dynamic
minimum width (never below 400 pixels); a requested value below that minimum is ignored. The final
image width is containerWidth + borderSize * 2.
The optional minLines field controls the minimum number of rendered code lines. When the submitted
code has fewer lines, the server appends blank lines so the image keeps a comfortable height. It
defaults to 3 and is capped at 1000.
The optional endSpaceLines field appends that many blank lines after the formatted code. It
defaults to 2 and is capped at 1000; pass 0 to disable it. Appended blank lines count toward line
numbers and lineCount and increase the image height.
After formatting, the server estimates a dynamic minContainerWidth from the widest rendered code
line using the Fira Code monospace metrics. The actual containerWidth is raised to at least this
dynamic minimum to avoid clipping code.
All account levels may use any bundled theme, supported output format, and background. Admin accounts have no API quota.
The optional theme field selects any bundled Shiki theme. Unknown themes fall back to dracula.
The optional style field selects the image layout. It defaults to default. Set style to vercel for
a black canvas with a thin frame and top-left/bottom-right corner crosses; this style keeps theme syntax highlighting but
does not render line numbers, avatars, or the language icon. Its dynamic minContainerWidth is always
greater than 440 pixels.
The optional innerPadding field controls the distance between vercel code and the frame lines.
It defaults to 16 pixels and is ignored by the default style.
The optional filename field adds a centered title in the image header between the mock window
controls and language icon. Title color is selected from the resolved theme so it remains legible
on light and dark code themes.
The optional bgColor field controls the outer area behind the code window. It supports #RRGGBB,
linear-gradient(...), and radial-gradient(...). The legacy backgroundColor field is still accepted
for compatibility.
The optional showLineNumbers field controls whether rendered images include line numbers.
The optional showLanguageIcon field controls whether rendered images include the language icon in
the top-right of the code window.
The optional showAvatar field controls whether rendered images include an avatar in the bottom-right
of the code window. Avatar rendering is available to Pro/Admin users. When showAvatar is true, the
optional avatarUrl field can provide an HTTP(S) image URL; if it is omitted, Codia uses the API
credential owner's account avatar when available. avatarSize controls the avatar width and height,
and avatarRadius controls the avatar corner radius.
The optional quality field controls output pixel density. It defaults to 1. Use 2 for high
quality and 3 for ultra quality. Layout dimensions stay the same, but output pixel width and
height are multiplied by quality.
The optional responseType field controls the HTTP response body. It defaults to json. Use image to
return generated image bytes directly with Content-Type set to the actual image MIME type. Use
cdnUrl as a Pro/Admin-only option to upload the generated image to configured Cloudflare
R2/S3-compatible storage and return a CDN URL. The legacy returnImage field remains accepted; returnImage: true behaves like
responseType: image.
Every successful render is recorded in SQLite as a lightweight generation event. Codia does
not store the submitted code, generated image base64 payload, data URL, or image file content.
Stored metadata includes language, theme, dimensions, line count, source, and timestamp.
Free signed-in users have a limit of 200 API images per calendar month. Paid users have a limit of
3,600 images per rolling 24 hours, while administrators have no limit.

### Request

Content-Type: application/json

Fields:

- code: string, required. Source code to render. Maximum length: 50,000 characters.
- language: string, optional. Shiki language id, such as typescript, javascript, python, go,
  rust, html, css, json, markdown, bash, or text. If omitted, the language is detected from the
  source code. Unknown languages fall back to text.
- format: string, optional. Defaults to webp. All account levels support webp, png, jpg, and jpeg.
- theme: string, optional. Defaults to dracula. All account levels support bundled themes.
- style: string, optional. Defaults to default. Set to vercel for the black thin-frame layout;
  vercel always hides line numbers, language icon, and avatar, and uses a minimum width greater than 440px.
- innerPadding: number, optional. Defaults to 16px for vercel. Controls the distance from code to
  the surrounding frame lines; range 0-120. Ignored by default style.
- filename: string, optional. Maximum length: 160 characters. If provided, it is shown as the
  centered header title between the mock window controls and language icon.
- bgColor: string, optional. Defaults to the sky cyan radial gradient. All account levels may use #RRGGBB, linear-gradient(...), and radial-gradient(...).
- backgroundColor: string, optional. Legacy alias for bgColor.
- borderSize: number, optional. Outer padding/border size in pixels. Default: 12. Maximum: 120.
- borderRadius: number, optional. Code window corner radius in pixels. Default: 4. When
  borderSize is greater than 0, the actual value is normalized to be greater than or equal to
  0 and smaller than borderSize. When borderSize is 0, the actual value is 0.
- containerWidth: number, optional. Requested code window width in pixels. Default: 600. Must be
  positive, maximum: 1920. The actual value may be raised to minContainerWidth.
- minLines: number, optional. Minimum rendered code line count. Defaults to 3; range 1-1000.
  Blank lines are appended when the code has fewer rendered lines.
- endSpaceLines: number, optional. Blank lines appended after the code. Defaults to 2; range
  0-1000. Appended blank lines are included in line numbers and lineCount.
- showLineNumbers: boolean, optional. Whether to show line numbers. Default: true.
- showLanguageIcon: boolean, optional. Whether to show the language icon in the header. Default: true.
- showAvatar: boolean, optional. Whether to show an avatar in the lower-right corner. Default: false.
  Avatar rendering is available to Pro/Admin users.
- avatarUrl: string, optional. HTTP(S) avatar image URL. Used when showAvatar is true; if omitted,
  Codia uses the API credential owner's account avatar when available.
- avatarSize: number, optional. Avatar width and height in pixels. Default: 26. Minimum: 24.
  Maximum: 128.
- avatarRadius: number, optional. Avatar corner radius in pixels. Default: 64. Minimum: 0.
  Maximum: 64.
- quality: number, optional. Output pixel density multiplier. Default: 1. Minimum: 1.
  Maximum: 3. Use 2 for high-quality browser previews.
- source: string, optional. One of api, try-it-preview, try-it-copy, try-it-download, or try-it-generate.
  Default: api. Every successful call increments the credential owner's API image count and render statistics once.
- responseType: string, optional. One of json, image, or cdnUrl. Default: json. cdnUrl requires
  a Pro/Admin API credential plus Cloudflare R2/S3-compatible storage environment variables.
- returnImage: boolean, optional. Legacy alias for responseType: image.

Authorization header:

Authorization: Bearer codia_<credential>

Example request:

```json
{
  "language": "typescript",
  "format": "png",
  "theme": "github-dark",
  "style": "vercel",
  "innerPadding": 16,
  "filename": "app.ts",
  "bgColor": "radial-gradient(circle at top center, rgba(106, 196, 226, 0.9) 0%, rgba(38, 143, 184, 0.85) 28%, rgba(9, 88, 132, 0.95) 60%, #062e55 100%)",
  "borderSize": 12,
  "borderRadius": 4,
  "containerWidth": 600,
  "minLines": 3,
  "endSpaceLines": 2,
  "showLineNumbers": true,
  "showLanguageIcon": true,
  "showAvatar": false,
  "avatarSize": 26,
  "avatarRadius": 64,
  "quality": 2,
  "responseType": "json",
  "code": "const message: string = \"Hello, Takumi\";\nconsole.log(message);"
}
```

### Response

Content-Type: application/json

This is the default response when responseType is omitted or json.

Fields:

- imageBase64: string. Image base64 payload without a data URL prefix.
- imageMd5: string. MD5 of the generated image bytes, also used as the CDN object key base.
- dataUrl: string. Image data URL that can be assigned directly to an img src.
- mimeType: "image/webp", "image/png", or "image/jpeg".
- format: "webp", "png", or "jpeg".
- language: string. Actual language used by Shiki. Unknown languages return text.
- theme: string. Actual Shiki theme used for rendering. Free accounts receive a GitHub theme.
- style: string. Actual layout style used for rendering: default or vercel.
- innerPadding: number. Actual vercel code-to-frame spacing in pixels; default style returns 0.
- filename: string or null. The normalized filename/title shown in the image header.
- bgColor: string. Actual outer background style used for rendering.
- backgroundColor: string. Legacy response field with the same value as bgColor.
- lineCount: number. Number of rendered code lines.
- showLineNumbers: boolean. Whether line numbers were shown.
- showLanguageIcon: boolean. Whether the language icon was shown.
- showAvatar: boolean. Whether an avatar was shown. This is false when showAvatar was requested
  but no usable avatar image could be resolved.
- avatarSize: number. Avatar width and height used for the render.
- avatarRadius: number. Avatar corner radius used for the render.
- borderSize: number. Outer padding/border size used for the render.
- borderRadius: number. Code window corner radius used for the render.
- minContainerWidth: number. Dynamic minimum code window width estimated from the widest
  formatted code line.
- containerWidth: number. Actual code window width used for the render.
- logicalWidth: number. Logical image width in CSS pixels, equal to containerWidth + borderSize * 2.
- logicalHeight: number. Logical image height in CSS pixels.
- width: number. Actual output image width in pixels, equal to logicalWidth * quality.
- height: number. Actual output image height in pixels, equal to logicalHeight * quality.
- quality: number. Output pixel density multiplier used for the render.
- recordId: number. SQLite render record id for this generated image.

Example response shape:

```json
{
  "imageBase64": "UklGRjIAAABXRUJQ...",
  "imageMd5": "8f14e45fceea167a5a36dedd4bea2543",
  "dataUrl": "data:image/webp;base64,UklGRjIAAABXRUJQ...",
  "mimeType": "image/webp",
  "format": "webp",
  "language": "typescript",
  "theme": "dracula",
  "filename": "app.ts",
  "bgColor": "radial-gradient(circle at top center, rgba(106, 196, 226, 0.9) 0%, rgba(38, 143, 184, 0.85) 28%, rgba(9, 88, 132, 0.95) 60%, #062e55 100%)",
  "backgroundColor": "radial-gradient(circle at top center, rgba(106, 196, 226, 0.9) 0%, rgba(38, 143, 184, 0.85) 28%, rgba(9, 88, 132, 0.95) 60%, #062e55 100%)",
  "lineCount": 3,
  "showLineNumbers": true,
  "showLanguageIcon": true,
  "showAvatar": false,
  "avatarSize": 26,
  "avatarRadius": 64,
  "borderSize": 12,
  "borderRadius": 4,
  "minContainerWidth": 400,
  "containerWidth": 600,
  "minLines": 3,
  "endSpaceLines": 2,
  "logicalWidth": 624,
  "logicalHeight": 188,
  "width": 1248,
  "height": 376,
  "quality": 2,
  "recordId": 42
}
```

When responseType is image, the response body is the generated image bytes. Content-Type is one of
image/webp, image/png, or image/jpeg. Metadata that is still useful for automation is exposed in
headers: x-codia-record-id, x-codia-format, x-codia-width, x-codia-height, and optionally
x-codia-filename.

When responseType is cdnUrl, the Pro/Admin-only API path uploads the generated image to Cloudflare
R2/S3-compatible storage. The object key is based on the generated image MD5, such as codia/<md5>.png.
Before uploading, the API sends an authenticated S3-compatible HEAD request; if the object already
exists, it skips the PUT and returns uploaded: false. The JSON response includes cdnUrl, imageMd5, storageKey,
uploaded, recordId, mimeType, format, filename, width, and height.

## MCP Server

Codia also exposes a Streamable HTTP MCP server at /mcp. MCP clients should use OAuth 2.1 with
PKCE: register the server URL, then complete the browser login and consent flow. In Codex, use:

codex mcp add codia --url https://your-codia-host.example/mcp
codex mcp login codia

The authorization page lets the signed-in user choose an existing API credential or generate a
new one. Existing Authorization: Bearer codia_<credential> API keys remain supported for clients
that do not support MCP OAuth. MCP requests should also accept application/json, text/event-stream.

The server provides two tools:

- render_code_image: the compact tool for agents. Its only fields are code, optional language,
  preset, output, and save. preset is one of github, twitter, docs, blog, glass, macos, or minimal;
  output is png, webp, or jpeg and defaults to png. save defaults to true and controls whether
  the generated image is included in the MCP response.
- render_code_image_advanced: the complete input model based on POST /v1/code/render. It exposes
  language, format, theme, filename, bgColor, backgroundColor, borderSize, borderRadius,
  containerWidth, minLines, endSpaceLines, showLineNumbers, showLanguageIcon, showAvatar,
  avatarUrl, avatarSize, avatarRadius, quality, responseType, source, and the MCP-only save
  response control in addition to code. save defaults to true.

Both render tools return a small JSON text summary containing the record id, resolved language,
format, theme, and output dimensions. By default they also return an MCP image content block. Set
save to false when the caller only needs the summary and does not want the image data in the
response. The MCP server does not persist generated image content.

## Stats Endpoint

GET /v1/code/stats

Returns aggregate SQLite render and satisfaction stats for the homepage and external tools, including
total renders, generated image count, satisfaction count, total rendered lines, top languages, and
recent generation records. Stats do not include stored code or image content.

## Satisfaction Endpoint

POST /v1/feedback/satisfaction

Record one successful /try-it copy or download action. Each successful action adds one satisfaction
event. The server stores only the action type and timestamp, not the code or image content.

Request body:

```json
{
  "action": "copy"
}
```

The action must be `copy` or `download`. The response includes `accepted: true` and the current
`totalSatisfactions` count.

## Human Preview

GET /playground

Returns an HTML page where users can choose a language, enter code, switch between editor and
final rendered image tabs, and copy or download the generated image. The legacy /try-it and
/example routes remain available; /example redirects to /playground.

## OpenAPI

GET /openapi.json
GET /api/docs

The human API usage guide is available at /docs. The human MCP guide is available at /docs/mcp.
OpenAPI JSON and Swagger UI are available at /api/docs.