HTMLPix API Skill

Use the API contracts below when generating code, curl commands, SDK wrappers, or troubleshooting responses.

Base URL and Auth

• API Base URL: https://api.htmlpix.com
• Private endpoints require: Authorization: Bearer <API_KEY>
• API keys are prefixed hpx_ and managed at https://htmlpix.com/api-keys
• Do not call private endpoints from browser client code; mint URLs on the backend.

Authentication Flow

Every private request goes through this pipeline:

1. Extract Authorization: Bearer <key> header
2. Hash the key with SHA-256, look up by hash in the apiKeys table
3. Verify key status is active (otherwise 403 KEY_INACTIVE)
4. Query the user's subscription status from quotas table
5. Subscription must be active, trialing, or canceled with time remaining

Error Codes

Endpoint Contracts

POST /v1/url (private)

Mint one signed image URL. The server resolves template variables, executes the template JSX, uploads the rendered VNode to Cloudflare R2/KV, and returns a signed URL pointing to the Cloudflare Worker that renders the final image.

Request JSON:

Response 200:

{ "url": "https://image.htmlpix.com/v1/image?...&sig=...", "expiresAt": 1710345600000 }

Operational limits:

• Body size max: 32 KB
• Rate: 120 mint requests per 60s per API key
• Concurrency: 4 in-flight per user
• URLs expire after ~5 years by default

POST /v1/urls (private)

Mint multiple signed image URLs in one request.

Request JSON:

{ "items": [ /* each item has same shape as POST /v1/url */ ] }

• items.length must be 1–25

Response 200:

{ "urls": [{ "templateId": "...", "url": "...", "expiresAt": 1710345600000 }] }

Operational limits:

• Body size max: 256 KB

GET /v1/image (public, signed — served by Cloudflare Worker)

Requests to api.htmlpix.com/v1/image are 301-redirected to the Cloudflare Worker at image.htmlpix.com/v1/image. The Worker renders the image from VNode data stored in R2/KV.

Required query params:

Optional query params:

Behavior:

• 403 URL_EXPIRED — URL past expiry
• 403 INVALID_SIGNATURE — params modified after signing
• Returns image bytes with immutable caching headers and ETag
• Supports 304 Not Modified via If-None-Match

Important: treat minted URLs as opaque. If any query value changes, signature validation fails.

GET /v1/templates (private)

List templates visible to the authenticated user.

Query params:

Response 200:

{ "templates": [ /* template objects */ ] }

POST /v1/templates (private)

Create a custom template. Templates are defined by a single code field containing JSX/TSX source code. The server compiles, validates, and extracts variables automatically.

Request JSON:

Legacy fields jsx, variables, googleFonts, width, height, format are rejected with error code LEGACY_TEMPLATE_PAYLOAD. Use code only.

Response 201:

{ "templateId": "abc123..." }

Error responses:

• 400 COMPILE_ERROR — JSX compilation or validation failed
• 400 LEGACY_TEMPLATE_PAYLOAD — sent a deprecated field

GET /v1/templates/:templateId (private)

Fetch one template visible to the caller.

Response 200:

{ "template": { /* template object */ } }

• 404 TEMPLATE_NOT_FOUND if not visible to caller

PATCH /v1/templates/:templateId (private)

Update template fields. At least one field required.

Request JSON:

Legacy fields jsx, variables, googleFonts, width, height, format are rejected.

Response 200:

{ "templateId": "abc123..." }

Error responses:

• 400 EMPTY_UPDATE — no updatable field provided
• 400 COMPILE_ERROR — JSX compilation failed
• 404 TEMPLATE_NOT_FOUND — template doesn't exist or not owned by caller

POST /v1/templates/generate (private)

AI-assisted template generation. Always uses batch format.

Request JSON:

{
  "items": [
    { "prompt": "A social card with bold title and gradient background", "width": 1200, "height": 630 }
  ]
}

Response 200:

{
  "results": [
    { "ok": true, "result": { /* generated template data */ } },
    { "ok": false, "error": "error message" }
  ]
}

Each item settles independently — some may succeed while others fail.

Error responses:

• 429 QUOTA_EXCEEDED — AI generation quota hit
• 402 SUBSCRIPTION_REQUIRED — paid plan needed
• 422 PARSE_FAILED — AI output couldn't be parsed
• 502 AI_NOT_CONFIGURED — AI provider not set up
• 502 GENERATION_FAILED — generic AI failure

Safe Integration Pattern

1. Keep API key server-side only.
2. Mint with POST /v1/url or /v1/urls on your backend.
3. Store/embed the returned url directly (meta tags, email HTML, social cards, etc.).
4. Do not re-sign or mutate query params client-side.
5. Handle 402, 429, and 503 with retries/fallback messaging.

Minimal Examples

# Mint a single image URL
curl -X POST https://api.htmlpix.com/v1/url \
  -H "Authorization: Bearer $HTMLPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tmpl_123",
    "variables": { "title": "Launch Day" },
    "width": 1200,
    "height": 630,
    "format": "png"
  }'

# List your templates
curl -X GET "https://api.htmlpix.com/v1/templates?scope=mine" \
  -H "Authorization: Bearer $HTMLPIX_API_KEY"

# Create a template from code
curl -X POST https://api.htmlpix.com/v1/templates \
  -H "Authorization: Bearer $HTMLPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Social Card",
    "code": "export default function Template({ title }) {\n  return <div style={{ fontSize: 48 }}>{title}</div>\n}"
  }'

# AI-generate a template
curl -X POST https://api.htmlpix.com/v1/templates/generate \
  -H "Authorization: Bearer $HTMLPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{ "prompt": "Minimalist blog post OG image with title and author" }]
  }'

If the user asks for an endpoint not listed above, say it is not present in the current server route table and avoid inventing routes.