Agents & API

A programmatic render API built for agents: deterministic, computable pricing, and scoped keys with bounded spend — so an agent can estimate cost and render without a human in the loop.

Organizations & service accounts

• An Organization is the billing entity — it owns the credit ledger. Every user automatically has a personal org.
• A Service account is an agent identity under an org: a scoped API key with an optional spend cap and expiry. It's a bounded mandate — a human grants an agent the right to spend up to $X on specific operations.

Get a key

Create a service account from your dashboard: Account → Service Accounts. Pick a name, scopes, and an optional spend cap. The key (pp_sa_…) is shown once — copy it then; only a hash is stored.

Authenticate

Send the key as a bearer token:

Authorization: Bearer pp_sa_xxxxxxxxxxxxxxxx

Scopes

A request without one of the required scopes is rejected with insufficient_scope. A spend cap is enforced before a render is held — once a key has charged up to its cap, further renders return 402.

Pricing is computable

Cost is deterministic, so an agent can bound it before calling:

credits = ceil(duration_s × fps_factor × resolution_factor × format_factor)
1 credit = 1s of 1080p/30 MP4 = $0.015

See the full table + calculator on the pricing page.

REST endpoints (/v1)

Estimate a render

curl -X POST https://cloud.pinepaper.studio/v1/renders:estimate \
  -H "Authorization: Bearer pp_sa_…" \
  -H "Content-Type: application/json" \
  -d '{"exportProfile":{"durationSeconds":10,"fps":30,"resolution":"1080p","format":"mp4"}}'

# → { "ok": true, "credits": 10, "priceUsd": 0.15, "breakdown": {…} }

Validate a scene

curl -X POST https://cloud.pinepaper.studio/v1/scenes:validate \
  -H "Authorization: Bearer pp_sa_…" \
  -H "Content-Type: application/json" \
  -d '{"scene":{"canvas":{"width":1920,"height":1080},"layers":[…]}}'

# → { "valid": true, "diagnostics": [], "itemCount": 12, "dimensions": {…} }

Render a scene (SVG)

curl -X POST https://cloud.pinepaper.studio/v1/renders \
  -H "Authorization: Bearer pp_sa_…" \
  -H "Content-Type: application/json" \
  -d '{"scene":{…},"exportProfile":{"resolution":"1080p","format":"svg","durationSeconds":5,"fps":30}}'

# → { "ok": true, "status": "succeeded", "credits": 2, "priceUsd": 0.03,
#     "cached": false, "statusUrl": "…/v1/renders/rnd_…",
#     "artifactUrl": "…/v1/renders/rnd_…/artifact" }
# Then GET the artifactUrl for the SVG. A raster format returns 503 worker_pending.

Errors use one diagnostic vocabulary everywhere — { code, severity, target, fix } — plus service codes INSUFFICIENT_CREDITS, LIMIT_EXCEEDED.

MCP tools

The same capabilities are exposed as MCP tools for Claude Desktop and other MCP clients via https://cloud.pinepaper.studio/mcp/v1:

{
  "mcpServers": {
    "pinepaper-cloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://cloud.pinepaper.studio/mcp/v1"]
    }
  }
}

See also: pricing · status · security · general docs.