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.

OpenAPI Specification

The full OpenAPI 3.1 specification is available at:

text

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

You can import this into tools like Postman, Insomnia, or use it with code generators.