Initial marketplace with flamenco and kitsu plugins
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>
This commit is contained in:
Claude Opus 4.7
@@ -0,0 +1,189 @@
|
||||
---
|
||||
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.
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user