Chertila

Automation API

Create API keys for images, generation, frame previews, editing, favorites, and renders.

Your API keys

A key can access your styles, images, animations, frame previews, favorites, edits, and renders. The full value is shown only once.

Loading...

Documentation

Generation, editing, and rendering are asynchronous: start the job, then poll its status endpoint.

GET/api/v1/styles

Returns default styles and the current user's styles. Use the selected style id for generation.

Request
GET /api/v1/styles HTTP/1.1
Authorization: Bearer $CHERTILA_API_KEY
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [
    {
      "id": "modern-apple-dark",
      "name": "Modern Apple Dark",
      "description": "Sleek, clean, and premium dark mode design.",
      "source": "default",
      "fonts": {
        "heading": "Inter, system-ui, sans-serif",
        "body": "Inter, system-ui, sans-serif",
        "mono": "JetBrains Mono, monospace"
      },
      "colors": {
        "background": "#000000",
        "surface": "#1C1C1E",
        "primary": "#2997FF",
        "secondary": "#E5E5EA",
        "accent": "#FF453A",
        "text": "#F5F5F7",
        "muted": "#98989D"
      },
      "style_prompt": "Emulate modern Apple keynotes in dark mode..."
    }
  ]
}
curl
curl -s "https://chertila.app/api/api/v1/styles" \
  -H "Authorization: Bearer $CHERTILA_API_KEY"
GET/api/v1/images

Returns the user's paginated image library with short-lived signed original and thumbnail URLs.

Request
GET /api/v1/images?page=1&page_size=24 HTTP/1.1
Authorization: Bearer $CHERTILA_API_KEY
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [
    {
      "id": "a9a01df4-8397-4307-a198-d384eb060c7d",
      "original_filename": "diagram.png",
      "content_type": "image/png",
      "width": 1600,
      "height": 900,
      "file_size": 248120,
      "url": "https://signed-r2-url.example/original",
      "thumbnail_url": "https://signed-r2-url.example/thumbnail",
      "created_at": "2026-08-17T10:00:00Z"
    }
  ],
  "page": 1,
  "page_size": 24,
  "total": 1,
  "total_pages": 1
}
curl
curl -s "https://chertila.app/api/api/v1/images?page=1&page_size=24" \
  -H "Authorization: Bearer $CHERTILA_API_KEY"
POST/api/v1/images

Uploads a PNG, JPEG, WebP, or GIF to the user's private R2 image library.

Request
POST /api/v1/images HTTP/1.1
Authorization: Bearer $CHERTILA_API_KEY
Content-Type: multipart/form-data

file=@./diagram.png
Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "a9a01df4-8397-4307-a198-d384eb060c7d",
  "original_filename": "diagram.png",
  "content_type": "image/png",
  "width": 1600,
  "height": 900,
  "file_size": 248120,
  "url": "https://signed-r2-url.example/original",
  "thumbnail_url": "https://signed-r2-url.example/thumbnail",
  "created_at": "2026-08-17T10:00:00Z"
}
curl
curl -s -X POST "https://chertila.app/api/api/v1/images" \
  -H "Authorization: Bearer $CHERTILA_API_KEY" \
  -F "file=@./diagram.png"
POST/api/v1/images/resolve

Refreshes metadata and signed URLs for up to 10 image asset ids while preserving request order.

Request
POST /api/v1/images/resolve HTTP/1.1
Authorization: Bearer $CHERTILA_API_KEY
Content-Type: application/json

{
  "ids": ["a9a01df4-8397-4307-a198-d384eb060c7d"]
}
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [
    {
      "id": "a9a01df4-8397-4307-a198-d384eb060c7d",
      "original_filename": "diagram.png",
      "content_type": "image/png",
      "width": 1600,
      "height": 900,
      "file_size": 248120,
      "url": "https://signed-r2-url.example/original",
      "thumbnail_url": "https://signed-r2-url.example/thumbnail",
      "created_at": "2026-08-17T10:00:00Z"
    }
  ]
}
curl
curl -s -X POST "https://chertila.app/api/api/v1/images/resolve" \
  -H "Authorization: Bearer $CHERTILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":["a9a01df4-8397-4307-a198-d384eb060c7d"]}'
POST/api/v1/animations

Starts animation generation from a prompt and style id. It spends credits like a normal generation.

Request
POST /api/v1/animations HTTP/1.1
Authorization: Bearer $CHERTILA_API_KEY
Content-Type: application/json

{
  "prompt": "Explain cash flow with a waterfall chart.",
  "style_id": "modern-apple-dark",
  "title": "Cash flow waterfall",
  "voiceover_script": "Optional narration text",
  "image_asset_ids": ["a9a01df4-8397-4307-a198-d384eb060c7d"]
}
Response
HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "generation_id": "2f0c4e5c-8a31-44f8-9b19-1b05d9027c9b",
  "status": "queued",
  "status_url": "https://chertila.app/api/api/v1/generations/2f0c4e5c-8a31-44f8-9b19-1b05d9027c9b"
}
curl
curl -s -X POST "https://chertila.app/api/api/v1/animations" \
  -H "Authorization: Bearer $CHERTILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Explain cash flow with a waterfall chart.","style_id":"modern-apple-dark","image_asset_ids":["a9a01df4-8397-4307-a198-d384eb060c7d"]}'
GET/api/v1/generations/{generation_id}

Returns generation status. When complete, the response includes animation_url for browser viewing.

Request
GET /api/v1/generations/{generation_id} HTTP/1.1
Authorization: Bearer $CHERTILA_API_KEY
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "generation_id": "2f0c4e5c-8a31-44f8-9b19-1b05d9027c9b",
  "status": "completed",
  "error": null,
  "animation_id": "7a6cb25d-4b0f-4a67-bc78-cdd0d11de9d2",
  "animation_url": "https://chertila.app/animation/7a6cb25d-4b0f-4a67-bc78-cdd0d11de9d2"
}
curl
curl -s "https://chertila.app/api/api/v1/generations/$GENERATION_ID" \
  -H "Authorization: Bearer $CHERTILA_API_KEY"
GET/api/v1/animations

Lists the user's animations. Set favorites_only=true to return only favorited animations.

Request
GET /api/v1/animations?favorites_only=true&limit=50&offset=0 HTTP/1.1
Authorization: Bearer $CHERTILA_API_KEY
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [
    {
      "id": "7a6cb25d-4b0f-4a67-bc78-cdd0d11de9d2",
      "prompt_preview": "Explain cash flow with a waterfall chart.",
      "prompt_truncated": false,
      "title": "Cash flow waterfall",
      "current_version_id": "ba9ad4d2-f88a-4ac2-ad9c-14fd6cbe47de",
      "is_favorite": true,
      "image_asset_ids": ["a9a01df4-8397-4307-a198-d384eb060c7d"],
      "animation_url": "https://chertila.app/animation/7a6cb25d-4b0f-4a67-bc78-cdd0d11de9d2",
      "created_at": "2026-08-17T10:05:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
curl
curl -s "https://chertila.app/api/api/v1/animations?favorites_only=true&limit=50&offset=0" \
  -H "Authorization: Bearer $CHERTILA_API_KEY"
GET/api/v1/animations/{animation_id}

Returns one owned animation, its favorite flag, current version, and selected image asset ids.

Request
GET /api/v1/animations/{animation_id} HTTP/1.1
Authorization: Bearer $CHERTILA_API_KEY
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "7a6cb25d-4b0f-4a67-bc78-cdd0d11de9d2",
  "prompt_preview": "Explain cash flow with a waterfall chart.",
  "prompt_truncated": false,
  "title": "Cash flow waterfall",
  "current_version_id": "ba9ad4d2-f88a-4ac2-ad9c-14fd6cbe47de",
  "is_favorite": true,
  "image_asset_ids": ["a9a01df4-8397-4307-a198-d384eb060c7d"],
  "animation_url": "https://chertila.app/animation/7a6cb25d-4b0f-4a67-bc78-cdd0d11de9d2",
  "created_at": "2026-08-17T10:05:00Z"
}
curl
curl -s "https://chertila.app/api/api/v1/animations/$ANIMATION_ID" \
  -H "Authorization: Bearer $CHERTILA_API_KEY"
GET/api/v1/animations/{animation_id}/frame

Synchronously renders an exact PNG frame at time_ms for vision review before a full video render. Omit version_id for the current version or pass an edit's version id.

Request
GET /api/v1/animations/{animation_id}/frame?time_ms=2500&version_id={version_id}&resolution=720p HTTP/1.1
Authorization: Bearer $CHERTILA_API_KEY
Response
HTTP/1.1 200 OK
Content-Type: image/png
Cache-Control: no-store
X-Chertila-Animation-Id: 7a6cb25d-4b0f-4a67-bc78-cdd0d11de9d2
X-Chertila-Version-Id: ba9ad4d2-f88a-4ac2-ad9c-14fd6cbe47de
X-Chertila-Time-Ms: 2500
X-Chertila-Duration-Ms: 12000
X-Chertila-Width: 1280
X-Chertila-Height: 720

(PNG binary)
curl
curl -s "https://chertila.app/api/api/v1/animations/$ANIMATION_ID/frame?time_ms=2500&version_id=$VERSION_ID&resolution=720p" \
  -H "Authorization: Bearer $CHERTILA_API_KEY" \
  --output frame-2500ms.png
PUT/api/v1/animations/{animation_id}/favorite

Adds or removes an owned animation from favorites.

Request
PUT /api/v1/animations/{animation_id}/favorite HTTP/1.1
Authorization: Bearer $CHERTILA_API_KEY
Content-Type: application/json

{
  "is_favorite": true
}
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "7a6cb25d-4b0f-4a67-bc78-cdd0d11de9d2",
  "is_favorite": true
}
curl
curl -s -X PUT "https://chertila.app/api/api/v1/animations/$ANIMATION_ID/favorite" \
  -H "Authorization: Bearer $CHERTILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_favorite":true}'
POST/api/v1/animations/{animation_id}/edits

Starts an edit from the current or specified version. Omit image_asset_ids to inherit, pass [] to remove all, or pass up to 10 ids to replace the set.

Request
POST /api/v1/animations/{animation_id}/edits HTTP/1.1
Authorization: Bearer $CHERTILA_API_KEY
Content-Type: application/json

{
  "instruction": "Replace the diagram and make the labels larger.",
  "base_version_id": "ba9ad4d2-f88a-4ac2-ad9c-14fd6cbe47de",
  "image_asset_ids": ["a9a01df4-8397-4307-a198-d384eb060c7d"]
}
Response
HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "edit_id": "859bf645-6793-4050-87fe-bd83dd4531e2",
  "status": "queued",
  "status_url": "https://chertila.app/api/api/v1/edits/859bf645-6793-4050-87fe-bd83dd4531e2"
}
curl
curl -s -X POST "https://chertila.app/api/api/v1/animations/$ANIMATION_ID/edits" \
  -H "Authorization: Bearer $CHERTILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instruction":"Replace the diagram and make the labels larger.","image_asset_ids":["a9a01df4-8397-4307-a198-d384eb060c7d"]}'
GET/api/v1/edits/{edit_id}

Returns edit status and the new version id after completion.

Request
GET /api/v1/edits/{edit_id} HTTP/1.1
Authorization: Bearer $CHERTILA_API_KEY
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "edit_id": "859bf645-6793-4050-87fe-bd83dd4531e2",
  "status": "completed",
  "error": null,
  "animation_id": "7a6cb25d-4b0f-4a67-bc78-cdd0d11de9d2",
  "version_id": "6d864c3c-ea75-4f9c-8fbb-0be5ab079ae0",
  "animation_url": "https://chertila.app/animation/7a6cb25d-4b0f-4a67-bc78-cdd0d11de9d2"
}
curl
curl -s "https://chertila.app/api/api/v1/edits/$EDIT_ID" \
  -H "Authorization: Bearer $CHERTILA_API_KEY"
POST/api/v1/animations/{animation_id}/renders

Starts rendering the current animation version with the selected resolution and format.

Request
POST /api/v1/animations/{animation_id}/renders HTTP/1.1
Authorization: Bearer $CHERTILA_API_KEY
Content-Type: application/json

{
  "resolution": "1080p",
  "format": "mp4"
}
Response
HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "render_id": "f16f8551-b28b-462c-9fa1-3ae528d68db1",
  "status": "queued",
  "status_url": "https://chertila.app/api/api/v1/renders/f16f8551-b28b-462c-9fa1-3ae528d68db1",
  "resolution": "1080p",
  "format": "mp4"
}
curl
curl -s -X POST "https://chertila.app/api/api/v1/animations/$ANIMATION_ID/renders" \
  -H "Authorization: Bearer $CHERTILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resolution":"1080p","format":"mp4"}'
GET/api/v1/renders/{render_id}

Returns render status. When the file is ready, the response includes a secret file_url without auth.

Request
GET /api/v1/renders/{render_id} HTTP/1.1
Authorization: Bearer $CHERTILA_API_KEY
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "render_id": "f16f8551-b28b-462c-9fa1-3ae528d68db1",
  "status": "completed",
  "error": null,
  "animation_id": "7a6cb25d-4b0f-4a67-bc78-cdd0d11de9d2",
  "resolution": "1080p",
  "format": "mp4",
  "file_url": "https://chertila.app/api/api/v1/files/renders/xkx6f5HqN5Oq99fFMXlIwr2W8WZTlDcF8v6MZd5EqVY"
}
curl
curl -s "https://chertila.app/api/api/v1/renders/$RENDER_ID" \
  -H "Authorization: Bearer $CHERTILA_API_KEY"