API Reference

API Overview

The Efecto API is a RESTful API that provides programmatic access to create posters, apply visual effects, and render images.

Base URL

text

https://efecto.app/api/v1

All API endpoints are relative to this base URL.

Authentication

The Efecto API is currently free and open. No authentication is required.

Quick Example

Create a poster with one API call. Copy this and modify it:

create-poster.sh

curl https://efecto.app/api/v1/state/encode \
  -H "Content-Type: application/json" \
  -d '{
  "state": {
    "canvas": { "aspectRatio": "9:16", "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": "#1a1a1a"
      },
      {
        "id": "title", "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
      }
    ],
    "effect": { "effectId": "ascii-standard", "enabled": true, "ascii": { "cellSize": 8, "color": true } }
  }
}'

Returns a shareable URL. Use Discovery endpoints to find available effects, fonts, and palettes.

Rate Limits

Endpoint Category	Rate Limit
Discovery (effects, fonts, etc.)	100 requests/minute
State (validate, encode, decode)	100 requests/minute
Render	10 requests/minute

Request Format

For POST requests, send JSON in the request body with the Content-Type: application/json header.

request.http

POST /api/v1/state/encode
Content-Type: application/json

{
  "state": {
    "canvas": { "aspectRatio": "16:9", "backgroundColor": "#1a1a1a" },
    "layers": [...]
  },
  "baseUrl": "https://efecto.app"
}

Response Format

All responses are JSON except for the render endpoint which returns binary image data.

response.json

{
  "url": "https://efecto.app/canvas?lm=1&ca=16:9&cbg=%231a1a1a&...",
  "params": "lm=1&ca=16:9&cbg=%231a1a1a&..."
}

Errors

Errors return appropriate HTTP status codes with a JSON body:

error.json

{
  "error": "Invalid state: missing canvas dimensions",
  "code": "INVALID_STATE"
}

Status	Description
`200`	Success
`400`	Bad Request - Invalid input
`429`	Too Many Requests - Rate limited
`500`	Internal Server Error

Available Endpoints

Discovery

List available options before creating a poster.

GET/effects

List all visual effects with their parameters

GET/fonts

List available fonts for text layers

GET/palettes

List color palettes for dither effects

GET/materials

List 3D materials

GET/shaders

List procedural shader backgrounds

GET/postprocess

List post-processing effects and presets

GET/images/search

Search free stock images from Lummi

State

Validate, encode, and decode poster state.

POST/state/validate

Validate a LayerShareState structure

POST/state/encode

Encode state to shareable URL

POST/state/decode

Decode URL back to state

GET/schema

Get JSON Schema for state and layer types

Render

Generate images from poster state.

POST/render

Render state to image (returns binary data)

Technical Notes

The API uses LayerShareState format. Canvas uses aspectRatio (not width/height). See the State Endpoints documentation for the required structure.

API Specifications

The FX endpoints above are documented in the Discovery and State sections. For the full Design API (sessions, tools, sharing, publishing), see the OpenAPI spec:

text

https://efecto.app/api/v1/design/openapi.json