Joseph HENRY
3600c870cd
Bundles the flamenco-api and kitsu-api skills as Claude Code plugins under an "adm-tools" marketplace. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
190 lines
8.0 KiB
Markdown
190 lines
8.0 KiB
Markdown
---
|
||
name: flamenco-api
|
||
description: >
|
||
Flamenco render farm manager API reference, configuration, and usage guide.
|
||
Use this skill whenever working with Flamenco — querying jobs, workers, tasks, or farm status via
|
||
the REST API, writing curl commands or Python scripts that talk to the Flamenco Manager,
|
||
configuring the manager or workers, troubleshooting render farm issues, managing worker tags
|
||
or sleep schedules, creating custom job types, or understanding how Flamenco integrates with
|
||
Blender. Also use when the user mentions render farm, farm status, render workers, job submission,
|
||
or Flamenco in any context. Trigger on mentions of flamenco, render farm, render worker,
|
||
farm status, job queue, render job, or worker management in the context of rendering.
|
||
---
|
||
|
||
# Flamenco Render Farm
|
||
|
||
[Flamenco](https://flamenco.blender.org/) is the render farm manager developed by the Blender
|
||
Foundation. It consists of a **Manager** (HTTP server, web UI, REST API) and one or more
|
||
**Workers** that pull jobs from the Manager and execute them — usually Blender renders, but the
|
||
job-type system is generic enough for ffmpeg encodes, file copies, or anything else.
|
||
|
||
## Setup before answering
|
||
|
||
Flamenco is self-hosted, so the Manager URL is site-specific. Before constructing API calls:
|
||
|
||
1. Check the user's environment for a Manager URL (env var like `FLAMENCO_MANAGER_URL`,
|
||
project config, or `CLAUDE.md`). The Manager web UI and the REST API share the same host;
|
||
`/api/v3/` is the API prefix.
|
||
2. If you can't find one, ask the user. Don't invent a URL.
|
||
|
||
In examples below, `<MANAGER_URL>` is a placeholder for the user's Manager root
|
||
(e.g. `https://flamenco.example.com` or `http://localhost:8080`). The API base is
|
||
`<MANAGER_URL>/api/v3/`.
|
||
|
||
Useful endpoints on any Manager:
|
||
|
||
- Web UI: `<MANAGER_URL>/`
|
||
- Swagger UI: `<MANAGER_URL>/api/v3/swagger-ui/`
|
||
- OpenAPI spec: `<MANAGER_URL>/api/v3/openapi3.json`
|
||
|
||
The API has no authentication by default — Flamenco assumes a trusted LAN. If the user has
|
||
fronted it with a reverse proxy that adds auth, account for that.
|
||
|
||
## Quick API examples
|
||
|
||
```bash
|
||
# Farm status (one of: active, idle, waiting, asleep, inoperative, unknown, starting)
|
||
curl -s <MANAGER_URL>/api/v3/status
|
||
|
||
# Manager version
|
||
curl -s <MANAGER_URL>/api/v3/version
|
||
|
||
# List all workers
|
||
curl -s <MANAGER_URL>/api/v3/worker-mgt/workers
|
||
|
||
# List all jobs
|
||
curl -s <MANAGER_URL>/api/v3/jobs
|
||
|
||
# Get a specific job
|
||
curl -s <MANAGER_URL>/api/v3/jobs/{job_id}
|
||
|
||
# Get tasks for a job
|
||
curl -s <MANAGER_URL>/api/v3/jobs/{job_id}/tasks
|
||
|
||
# Get task details (commands, status, assigned worker)
|
||
curl -s <MANAGER_URL>/api/v3/tasks/{task_id}
|
||
|
||
# Tail a task's log as plain text
|
||
curl -s <MANAGER_URL>/api/v3/tasks/{task_id}/logtail
|
||
|
||
# Query jobs by status (note: jobs query is POST, not GET)
|
||
curl -s <MANAGER_URL>/api/v3/jobs \
|
||
-X POST -H 'Content-Type: application/json' \
|
||
-d '{"status_in": ["failed"], "order_by": ["updated_at"], "limit": 5}'
|
||
|
||
# Change worker status (awake, asleep, offline, restart) — is_lazy waits for current task
|
||
curl -X POST <MANAGER_URL>/api/v3/worker-mgt/workers/{worker_id}/setstatus \
|
||
-H 'Content-Type: application/json' -d '{"status": "awake", "is_lazy": false}'
|
||
|
||
# Cancel / pause / requeue a job
|
||
curl -X POST <MANAGER_URL>/api/v3/jobs/{job_id}/setstatus \
|
||
-H 'Content-Type: application/json' -d '{"status": "canceled", "reason": "no longer needed"}'
|
||
```
|
||
|
||
## Key concepts
|
||
|
||
- **Job**: A render request, typically submitted from the Blender add-on. Carries settings
|
||
(blend file, frame range, output path, format) and is compiled by the Manager into tasks.
|
||
- **Task**: An executable unit within a job (e.g. "render frames 1–10"). Assigned to one worker
|
||
at a time. A task contains one or more **commands**.
|
||
- **Command**: The lowest-level operation a worker runs (e.g. `blender-render`, `move-directory`,
|
||
`frames-to-video`). Defined by the worker code; referenced by job-type scripts.
|
||
- **Worker**: A machine that polls the Manager for tasks and executes them. Has a status
|
||
(awake, asleep, offline, error, …) and a list of supported task types.
|
||
- **Tag**: A grouping label for workers. Jobs can be restricted to a tag so they only run on
|
||
matching workers (e.g. a `gpu` tag for GPU-only nodes).
|
||
- **Job type**: A JavaScript file in the Manager's `scripts/` directory that defines settings
|
||
and the compile function (turns a submitted job into a sequence of tasks). Built-in types
|
||
like `simple-blender-render` cover the common cases; custom types add new behaviors.
|
||
- **Shaman**: Optional content-addressed file store. When enabled, files are uploaded by
|
||
SHA256+size and symlinked into per-job checkout dirs. When disabled, files are referenced
|
||
in place on shared storage.
|
||
|
||
## Status enums
|
||
|
||
- **Job**: `active`, `canceled`, `completed`, `failed`, `paused`, `pause-requested`, `queued`,
|
||
`cancel-requested`, `requeueing`, `under-construction`
|
||
- **Task**: `active`, `canceled`, `completed`, `failed`, `queued`, `soft-failed`, `paused`
|
||
- **Worker**: `starting`, `awake`, `asleep`, `error`, `testing`, `offline`, `restart`
|
||
- **Farm**: `active`, `idle`, `waiting`, `asleep`, `inoperative`, `unknown`, `starting`
|
||
|
||
## Python SDK
|
||
|
||
Flamenco ships an auto-generated Python client (`flamenco-manager` on PyPI, importable as
|
||
`flamenco.manager`):
|
||
|
||
```python
|
||
from flamenco.manager import ApiClient, Configuration
|
||
from flamenco.manager.api import JobsApi, WorkerMgtApi, MetaApi
|
||
|
||
configuration = Configuration(host="<MANAGER_URL>")
|
||
api_client = ApiClient(configuration)
|
||
|
||
meta_api = MetaApi(api_client)
|
||
print(meta_api.get_version()) # FlamencoVersion
|
||
|
||
jobs_api = JobsApi(api_client)
|
||
jobs = jobs_api.fetch_jobs()
|
||
failed = [j for j in jobs.jobs if j.status == "failed"]
|
||
|
||
worker_api = WorkerMgtApi(api_client)
|
||
for w in worker_api.fetch_workers().workers:
|
||
print(f"{w.name}: {w.status}")
|
||
```
|
||
|
||
For ad-hoc scripts, plain `requests` against the REST API is often simpler and avoids the SDK
|
||
dependency.
|
||
|
||
## Submitting a job
|
||
|
||
Two endpoints take the same body — `POST /api/v3/jobs/check` validates without inserting,
|
||
`POST /api/v3/jobs` actually submits. Always send `submitter_platform` (`linux`, `windows`,
|
||
`darwin`, or `manager`) so the Manager can apply path replacements.
|
||
|
||
```bash
|
||
curl -X POST <MANAGER_URL>/api/v3/jobs \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{
|
||
"name": "Test render",
|
||
"type": "simple-blender-render",
|
||
"priority": 50,
|
||
"submitter_platform": "linux",
|
||
"settings": {
|
||
"blendfile": "/render/scene.blend",
|
||
"frames": "1-100",
|
||
"chunk_size": 5,
|
||
"render_output_path": "/render/output/######",
|
||
"format": "PNG"
|
||
},
|
||
"metadata": {"project": "demo", "user.name": "artist"}
|
||
}'
|
||
```
|
||
|
||
The exact `settings` keys depend on the job type. List available types with
|
||
`GET /api/v3/jobs/types`, or fetch one with `GET /api/v3/jobs/type/{typeName}` to see its
|
||
declared settings.
|
||
|
||
## Reference files
|
||
|
||
For complete details, read these as needed — they're verbose and only worth loading when
|
||
you're actually constructing API calls or troubleshooting:
|
||
|
||
- **`references/api-reference.md`**: Every endpoint with parameters, request/response schemas,
|
||
status codes, and curl examples. Read this when constructing a specific API call or
|
||
understanding a response shape.
|
||
- **`references/usage-docs.md`** (optional, may not be present): General Flamenco usage —
|
||
shared storage, manager/worker configuration, two-way variable replacement, custom job
|
||
types, failure handling, troubleshooting. Read this for setup or non-API questions.
|
||
|
||
If a reference file is missing or out of date, the canonical source is
|
||
`<MANAGER_URL>/api/v3/swagger-ui/` and `<MANAGER_URL>/api/v3/openapi3.json` — fetching the
|
||
OpenAPI JSON is the fastest way to verify a schema.
|
||
|
||
## Notes on the worker-side API
|
||
|
||
`/api/v3/worker/*` endpoints (`sign-on`, `sign-off`, `register-worker`, `state`,
|
||
`state-changed`, `task`, `task/{id}`, `task/{id}/may-i-run`, `task/{id}/output-produced`)
|
||
exist for the worker process to talk back to the Manager. They are not normally called by
|
||
end-user scripts; only touch them if you're implementing a custom worker or debugging the
|
||
worker protocol.
|