API Reference

Render Endpoints

Generate images from poster state using an external screenshot service.

Rate limited to 10 requests/minute. The render endpoint uses a screenshot API to capture the poster as it would appear in the browser, including all effects and post-processing.

Server configuration required

The render endpoint requires a SCREENSHOT_API_KEY environment variable. Get a free key (100 screenshots/month) from ScreenshotOne or ApiFlash.

Render Poster

POST/api/v1/render

Render state to image. Returns binary image data directly.

Request Body

Parameter	Type	Description
`state`required	`LayerShareState`	The poster state to render (see State docs)
`format`	`string`	Output format: png, jpeg, or webpDefault: `png`
`width`	`number`	Output width in pixels (100-3840)Default: `1080`
`height`	`number`	Output height in pixels (100-2160)Default: `1920`
`quality`	`number`	JPEG/WebP quality (1-100, ignored for PNG)Default: `90`

request.json

{
  "state": {
    "canvas": {
      "aspectRatio": "16:9",
      "backgroundColor": "#1a1a1a"
    },
    "layers": [
      {
        "id": "bg",
        "name": "Background",
        "type": "background",
        "visible": true,
        "locked": false,
        "transform": {
          "x": 0, "y": 0, "width": 1, "height": 1,
          "rotation": 0, "opacity": 1
        },
        "contentType": "solid",
        "solidColor": "#2a2a2a"
      },
      {
        "id": "text-1",
        "name": "Title",
        "type": "text",
        "visible": true,
        "locked": false,
        "transform": {
          "x": 0, "y": 0, "width": 1, "height": 1,
          "rotation": 0, "opacity": 1
        },
        "content": "Hello World",
        "fontFamily": "DM Sans",
        "fontSize": 64,
        "fontWeight": "bold",
        "color": "#ffffff",
        "textAlign": "center",
        "letterSpacing": 0,
        "lineHeight": 1.2
      }
    ]
  },
  "format": "png",
  "width": 1200,
  "height": 630
}

Response

Returns the image as binary data with the appropriate Content-Type header (image/png, image/jpeg, or image/webp).

Example

render.sh

curl https://efecto.app/api/v1/render \
  -H "Content-Type: application/json" \
  -d '{
    "state": { ... },
    "format": "png",
    "width": 1200,
    "height": 630
  }' \
  --output poster.png

Error Response (503)

If the screenshot API is not configured, you'll get a 503 with setup instructions:

error-response.json

{
  "error": "Render failed",
  "details": "SCREENSHOT_API_KEY env var is required...",
  "setup": "Set SCREENSHOT_API_KEY in your environment. Free keys: https://screenshotone.com or https://apiflash.com"
}

Output Formats

Format	MIME Type	Best For
`png`	image/png	Lossless, transparency support
`jpeg`	image/jpeg	Photos, smaller file size
`webp`	image/webp	Best compression, modern browsers

Technical Notes

The render API expects LayerShareState format. See the State Endpoints documentation for the required structure including aspectRatio (not width/height), and complete layer fields.

Known Limitations

Requires SCREENSHOT_API_KEY environment variable to be set
Rate limiting: 10 requests per minute per IP
Maximum render dimensions: 3840x2160 pixels
Minimum render dimensions: 100x100 pixels
Screenshot service adds ~5 second delay for WebGL rendering
Free tier typically allows 100 screenshots/month