API de automatización

Crea claves API para imágenes, generación, vistas previas de fotogramas, edición, favoritos y renders.

Tus claves API

Una clave puede acceder a tus estilos, imágenes, animaciones, vistas previas de fotogramas, favoritos, ediciones y renders. El valor completo solo se muestra una vez.

Cargando...

Documentación

La generación, la edición y el render son asíncronos: inicia la tarea y consulta su endpoint de estado.

GET/api/v1/styles

Devuelve estilos predeterminados y estilos del usuario actual. Usa el id elegido para generar.

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

Devuelve la biblioteca paginada del usuario con URLs firmadas temporales para originales y miniaturas.

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

Sube un PNG, JPEG, WebP o GIF a la biblioteca privada del usuario en R2.

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

Actualiza metadatos y URLs firmadas para hasta 10 image asset ids conservando el orden solicitado.

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

Inicia una generación de animación con prompt e id de estilo. Consume créditos como una generación normal.

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}

Devuelve el estado de la generación. Al finalizar, la respuesta incluye animation_url para verla en el navegador.

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

Lista las animaciones del usuario. Usa favorites_only=true para devolver solo las favoritas.

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}

Devuelve una animación propia, su estado de favorito, la versión actual y los image asset ids seleccionados.

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

Renderiza de forma síncrona un fotograma PNG exacto en time_ms para revisarlo con visión antes del vídeo completo. Omite version_id para la versión actual o indica el id de una edición.

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

Añade o elimina una animación propia de favoritos.

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

Inicia una edición desde la versión actual o indicada. Omite image_asset_ids para heredar, usa [] para eliminar todas o pasa hasta 10 ids para sustituir el conjunto.

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}

Devuelve el estado de la edición y el id de la nueva versión al completarse.

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

Inicia el render de la versión actual de la animación con la resolución y el formato elegidos.

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}

Devuelve el estado del render. Cuando el archivo está listo, incluye una file_url secreta sin autenticación.

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"