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 key can be found at https://htmlpix.com/api-keys
• Do not call private endpoints from browser client code; mint URLs on the backend.

Auth/plan/quota failures map to:

• 401 MISSING_KEY or INVALID_KEY
• 403 KEY_INACTIVE
• 402 SUBSCRIPTION_INACTIVE
• 429 QUOTA_EXCEEDED
• 503 NOT_READY

Endpoint Contracts

POST /v1/url (private)

Mint one signed image URL.

Request JSON:

• templateId (required, string, max 128)
• width (optional int, 1..4096)
• height (optional int, 1..4096)
• format (optional: png | jpeg | webp)
• quality (optional int, 0..100)
• tv (optional string, max 128)
• variables (optional object, max 64 keys, each value must be JSON-serializable)

Response JSON:

• { "url": string, "expiresAt": number }

Operational limits (default server values):

• Body size max: 32KB
• Rate: 120 mint requests per 60s per API key
• Concurrency: 4 in-flight per user, 64 global

POST /v1/urls (private)

Mint multiple signed image URLs.

Request JSON:

• { "items": ImageUrlMintRequest[] }
• items.length must be 1..25
• Each item has the same shape as POST /v1/url

Response JSON:

• { "urls": [{ "templateId": string, "url": string, "expiresAt": number }] }

Operational limits:

• Body size max: 256KB

GET /v1/image (public, signed)

Render/fetch image bytes using a signed query string.

Required query params:

• templateId
• uid
• exp (unix ms)
• sig

Optional query params:

• width (default 1200)
• height (default 630)
• format (default webp)
• quality
• tv
• Variables encoded as v_<name>=<value>

Behavior:

• Rejects expired URL: 403 URL_EXPIRED
• Rejects bad signature: 403 INVALID_SIGNATURE
• Returns image bytes with immutable caching headers and ETag
• Supports 304 Not Modified with If-None-Match

Important: treat minted URL as opaque. If any query value changes, signature validation will fail.

GET /v1/templates (private)

List templates.

Query:

• scope optional: all | mine | starter (default: all)

Response:

• { "scope": "...", "templates": [...] }

POST /v1/templates (private)

Create custom template.

Request JSON:

• name required string (max 120)
• description optional string (max 2000)
• jsx required string (max 120000, validated for safe JSX subset)
• variables required array (max 100)
• googleFonts optional array (max 10 strings)
• width/height optional ints 1..4096
• format optional png | jpeg | webp

Response:

• 201 { "templateId": string, "template": object }

GET /v1/templates/:templateId (private)

Fetch one template visible to caller.

Response:

• { "template": object }

PATCH /v1/templates/:templateId (private)

Update template fields.

Request JSON:

• At least one field is required (EMPTY_UPDATE if none)
• Updatable fields: name, description, jsx, variables, googleFonts, width, height, format

Response:

• { "template": object }

POST /v1/templates/generate (private)

AI-assisted template generation.

Supports either:

• Single: { "prompt": string, "width"?: number, "height"?: number }
• Batch: { "items": [{ "prompt": string, "width"?: number, "height"?: number }] }

Rules:

• prompt max 2000 chars
• width/height default to 1200x630
• Batch max 5 items
• Upstream timeout default: 60s

Response:

• Single request: returns one generated result object
• Batch request: { "results": [...] }

Safe Integration Pattern

1. Keep API key server-side only.
2. Mint with POST /v1/url or /v1/urls.
3. Store/embed 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

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"
  }'

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

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.