# Platemark full reference

Platemark is a render API for images, short videos and PDFs. Fill a template with text and photo URLs and get back a finished PNG or vertical MP4, or send invoice, quote, receipt, certificate or letter fields and get back a PDF with the math done. REST API, remote MCP server for AI agents, 100 free credits a month.

Base URL: https://platemark.rowhousesoftware.com

## Authentication
Every /v1 call except POST /v1/accounts and GET /v1/templates needs "Authorization: Bearer pm_...".
POST /v1/accounts with {"email": "you@example.com"} returns {"account", "api_key", "plan", "credits_left"}. The key is shown once.
GET /v1/account returns plan, credits_left, monthly_credits, period_start and signing_secret.

## Make an image
POST /v1/images
Body: {"template": "<id>", "modifications": {"<slot>": "text or image URL", ...}, "response": "json" (optional)}
Returns image/png with header x-credits-left, or with response "json": {"data_url": "data:image/png;base64,...", "credits_left": n}.
A slot value can be a string or an object: {"text": "...", "color": "#hex"}, {"image_url": "https://..."}, {"text": "...", "bg": "#hex"} for pill slots. "background": {"color": "#hex"} recolors the canvas. An empty string hides a pill slot.
Example:
curl https://platemark.rowhousesoftware.com/v1/images -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"template": "og-image", "modifications": {"title": "How we cut month end to two days"}}' > og.png

## Signed image URLs (for og:image tags)
GET https://platemark.rowhousesoftware.com/v1/images/<template>.png?a=<account>&<slot>=<text>&s=<signature>
s = first 32 hex characters of HMAC-SHA256(signing_secret, "<template>?" + the sorted query without s). First load costs a credit; later loads come from cache.

## Make a video
POST /v1/videos
Body: {"scenes": [{"template": "<id>", "modifications": {...}, "seconds": 4, "motion": "zoom_in"}, {"image_url": "https://...", "seconds": 3, "motion": "pan_left"}], "transition": "fade" | "cut", "audio_url": "https://... mp3/m4a/aac/wav", "webhook_url": "https://..."}
- Up to 20 scenes and 90 seconds. Seconds per scene 1 to 30. Motion: none, zoom_in, zoom_out, pan_left, pan_right.
- All template scenes must share one size; photo scenes take that size.
- Returns 202 {"id", "status": "queued", "seconds", "credits"}. Credits are 0.5 per second, rounded up, charged at submit and refunded if the render fails.
GET /v1/videos/<id> returns {"status": "queued" | "rendering" | "done" | "failed", "url", "error"}. Finished files are at https://platemark.rowhousesoftware.com/files/<id>.mp4 for 30 days. The webhook gets the same JSON when the job ends.

## Make a PDF
POST /v1/documents
Body: {"type": "invoice" | "quote" | "receipt" | "certificate" | "letter", "response": "json" (optional), ...fields}
invoice fields: from {name, address, email, phone, tax_id}, to {name, address, email}, items [{description, detail, quantity, unit_price}], number, issue_date (YYYY-MM-DD), due_date or due_days, po_number, currency (ISO), locale, discount {percent | amount, label}, tax {percent | amount, label}, shipping, amount_paid, payment_instructions, notes, terms, accent (hex), paper ("letter" | "a4").
quote: invoice fields plus valid_until or valid_days. receipt: invoice fields plus paid_date and payment_method.
certificate: title, recipient, reason, kicker, presented, signatures [{name, role}], date, id.
letter: from, to, subject, body (blank lines split paragraphs), closing, signer, signer_role, date, footer.
Tax applies after discount. Amounts round half up to the cent. With response "json" the reply is {url, pages, credits, totals: {currency, subtotal, discount, tax, shipping, total, amount_paid, amount_due}}. Files stay at the URL for 30 days. 2 credits, plus 1 per page past the second.

## MCP
Remote MCP server, streamable HTTP: https://platemark.rowhousesoftware.com/mcp. Header "Authorization: Bearer pm_..." (optional until rendering).
Tools: list_templates {tag?}, render_image {template, modifications}, render_invoice {from, to, items, ...}, render_document {type, fields}, account_status, create_account {email}.

## Errors
JSON {"error": {"code", "message"}}. 401 bad_key, 402 no_credits, 400 unknown_layer / bad_image / bad_video, 404 no_template, 429 too_many_signups. Failed renders are never charged.

## Templates
### announcement-story: Announcement, story
Size 1080x1920. Tags: social, story, photo, 9:16. Preview: https://platemark.rowhousesoftware.com/previews/announcement-story.png
  - photo: image URL (https PNG, JPG or GIF under 4 MB)
  - kicker: text, sample "Starting Monday"
  - headline: text, sample "We're open until 9 on weeknights"
  - footer: text, sample "1120 Thames St"

### just-listed-square: Just listed (real estate)
Size 1080x1080. Tags: real estate, photo, 1:1. Preview: https://platemark.rowhousesoftware.com/previews/just-listed-square.png
  - photo: image URL (https PNG, JPG or GIF under 4 MB)
  - status: text, sample "Just listed"
  - price: text, sample "$489,000"
  - address: text, sample "2214 Fleet Street, Baltimore"
  - details: text, sample "3 beds  ·  2 baths  ·  1,640 sq ft"

### just-listed-story: Just listed, story
Size 1080x1920. Tags: real estate, photo, story, 9:16. Preview: https://platemark.rowhousesoftware.com/previews/just-listed-story.png
  - photo: image URL (https PNG, JPG or GIF under 4 MB)
  - status: text, sample "Just listed"
  - price: text, sample "$489,000"
  - address: text, sample "2214 Fleet Street, Baltimore"
  - details: text, sample "3 beds  ·  2 baths  ·  1,640 sq ft"
  - agent: text, sample "Dana Reyes, Harbor Homes"

### og-image: Link preview (OG image)
Size 1200x630. Tags: og, blog, 1.91:1. Preview: https://platemark.rowhousesoftware.com/previews/og-image.png
  - site: text, sample "ledgerline.com/blog"
  - title: text, sample "How we closed the books in two days instead of nine"
  - subtitle: text, sample "Three changes to month end that anyone can copy."

### og-image-photo: Link preview with photo
Size 1200x630. Tags: og, blog, photo, 1.91:1. Preview: https://platemark.rowhousesoftware.com/previews/og-image-photo.png
  - photo: image URL (https PNG, JPG or GIF under 4 MB)
  - site: text, sample "ledgerline.com"
  - title: text, sample "The month end checklist we actually use"
  - subtitle: text, sample "With the template, free."

### product-card-square: Product card
Size 1080x1080. Tags: ecommerce, product, 1:1. Preview: https://platemark.rowhousesoftware.com/previews/product-card-square.png
  - photo: image URL (https PNG, JPG or GIF under 4 MB)
  - badge: text, sample "New"
  - name: text, sample "Stoneware pour-over set"
  - detail: text, sample "Dripper, mug and 40 filters"
  - price: text, sample "$48"

### quote-card-square: Quote card
Size 1080x1080. Tags: . Preview: https://platemark.rowhousesoftware.com/previews/quote-card-square.png
  - accent: text
  - quote: text, sample "Ship the boring version first. Then make it better every week."
  - author: text, sample "Jane Okafor"
  - role: text, sample "Founder, Ledgerline"

### quote-card-story: Quote card, story
Size 1080x1920. Tags: quote, story, 9:16. Preview: https://platemark.rowhousesoftware.com/previews/quote-card-story.png
  - quote: text, sample "Ship the boring version first. Then make it better every week."
  - author: text, sample "Jane Okafor"
  - role: text, sample "Founder, Ledgerline"

### sale-banner-square: Sale announcement
Size 1080x1080. Tags: ecommerce, sale, 1:1. Preview: https://platemark.rowhousesoftware.com/previews/sale-banner-square.png
  - kicker: text, sample "This weekend only"
  - offer: text, sample "30% off everything"
  - detail: text, sample "Ends Sunday at midnight. Free shipping over $50."
  - code: text, sample "Code WEEKEND30"

### social-post-portrait: Social post, portrait
Size 1080x1350. Tags: social, 4:5. Preview: https://platemark.rowhousesoftware.com/previews/social-post-portrait.png
  - photo: image URL (https PNG, JPG or GIF under 4 MB)
  - kicker: text, sample "This week"
  - headline: text, sample "Pastries out of the oven at 7, gone by 10"
  - footer: text, sample "@corner.bakehouse"

### social-post-square: Social post over a photo
Size 1080x1080. Tags: social, photo, 1:1. Preview: https://platemark.rowhousesoftware.com/previews/social-post-square.png
  - photo: image URL (https PNG, JPG or GIF under 4 MB)
  - kicker: text, sample "Open Saturdays"
  - headline: text, sample "Pastries out of the oven at 7, gone by 10"

### video-thumbnail: Video thumbnail
Size 1280x720. Tags: youtube, thumbnail, photo, 16:9. Preview: https://platemark.rowhousesoftware.com/previews/video-thumbnail.png
  - photo: image URL (https PNG, JPG or GIF under 4 MB)
  - headline: text, sample "I closed the books in 2 days"
  - tag: text, sample "Month end"