Kitsu Developer

Appearance

Try Kitsu Free

Creating and Structuring a Production ​

This section describes how a developer can use the Kitsu API to create, structure, and configure a production, from initial project setup to defining assets, shots, tasks, and metadata that support pipeline tracking and automation.

1. Production Setup ​

Creating a Project ​

The project is the root container for all assets, shots, tasks, and metadata.

python
project = gazu.project.new_project(name="Agent 327", production_type="short", production_style="2d")

TIP

If your studio repeatedly creates similar projects, you can capture a project's configuration as a project template and pre-populate everything below — task types, statuses, asset types, metadata descriptors, production settings — by passing project_template= to new_project().

Adding People to the Project Team ​

After creating your project, you can add people (users) to the project team by assigning them to the project.

python
person = gazu.person.get_person_by_email("jane.doe@example.com")
project = gazu.project.get_project_by_name("Agent 327")

gazu.project.add_person_to_team(project, person)

This operation ensures the user has access to project data according to their assigned permissions and responsibilities.

2. Defining the Production Entities ​

The next step is defining what is being produced and how work is organized.

Defining Shot Structure ​

A production / project is organized hierarchically into episodes (optional, for episodic productions), sequences (series of shots), and shots.

Create episodes and sequences:

python
gazu.shot.new_episode(project, name)

gazu.shot.new_sequence(project, name, episode=None)

Adding a shot to a sequence:

python
gazu.shot.new_shot(
    project="",
    sequence="",
    name="",
    nb_frames=50,
    frame_in=0,
    frame_out=50,
    description="",
    data={}
)

Query or update shots:

python
shot = gazu.shot.get_shot(shot_id)

gazu.shot.update_shot(shot)

This hierarchy is critical for scheduling, task assignment, and reporting, so make sure to get it right from the start.

Defining Asset Types ​

Assets represent reusable production elements. Kitsu supports both standard and custom asset types like characters, props, sets / environments, vehicles, FX elements... or any studio-specific category.

Asset types define how assets are grouped, which tasks and statuses apply to them, and how they fit in the pipeline.

To create or configure asset types:

python
gazu.asset.new_asset_type(name)

gazu.asset.update_asset_type(asset_type)

Creating Assets ​

Once asset types are defined, you can begin creating assets for your production. Assets can be any kind of production element you want to track, organize, or assign work to (e.g. characters, props, locations, FX elements).

To create a new asset, specify the project, asset type, and a name. You can also provide a description and any additional metadata if needed.

python
gazu.asset.new_asset(project, asset_type, name, description="", data={})

To update an existing asset's information (such as description or metadata):

python
asset = gazu.asset.get_asset(asset_id)
asset["description"] = "Updated description"
gazu.asset.update_asset(asset)

Defining Task Types and Statuses ​

Tasks represent units of work (modeling, rigging, animation, etc.), while statuses represent progress (to do, in progress, review, approved, etc.).

Define task types:

python
task_type = gazu.task.get_task_type_by_name('Animation')
gazu.project.add_task_type(project, task_type, priority=1)

Movies uploaded on a task are encoded at the project's hd_bitrate_compression and ld_bitrate_compression (Mbit/s, 28 and 6 by default). A task type can use its own values in the project, for instance a lighter encoding for animatics or a heavier one for final lighting. Calling add_task_type again on a linked task type updates its bitrates and keeps its priority:

python
gazu.project.update_project({**project, "hd_bitrate_compression": 20})
gazu.project.add_task_type(
    project, task_type, priority=1, hd_bitrate_compression=12, ld_bitrate_compression=3
)

Define task statuses:

python
status = gazu.task.get_task_status_by_name("Approved")
gazu.project.add_task_status(project, status)

Create tasks:

python
task_type_names = ["Modeling", "Rigging", "Animation"]
task_types = [gazu.task.get_task_type_by_name(name) for name in task_type_names]

gazu.task.create_asset_tasks(asset, task_types)
gazu.task.create_shot_tasks(shot, task_types)

Assign tasks:

Retrieve and Assign a Task ​

python
modeling = gazu.task.get_task_type_by_name('Modeling')
main_char = gazu.asset.get_asset_by_name(project, 'Main character')
task = gazu.task.get_task_by_entity(main_char, modeling)
gazu.task.assign_task(task, person)

3. Managing Metadata ​

Most studios need to track data that goes beyond built-in fields. Kitsu supports this through metadata descriptors: extra fields listed in the data attribute of entities.

Defining Metadata Descriptors ​

python
gazu.project.add_metadata_descriptor(
    project,
    name,
    entity_type="Asset",
    data_type='string',
    choices=[],
    for_client=False,
    departments=[]
)

Valid entity types are "Asset", "Shot", "Edit", "Episode", "Sequence", "Project" and "Task".

Task Metadata Descriptors ​

Task descriptors are scoped to one task type of the project: pass the task_type_id argument (required for the "Task" entity type, forbidden for the others). The column then shows up on the task type page in Kitsu.

python
task_type = gazu.task.get_task_type_by_name("Compositing")
gazu.project.add_metadata_descriptor(
    project,
    "Render layer",
    entity_type="Task",
    task_type_id=task_type["id"],
)

Values live in the data dict of each task. Write them with the merge helper so other keys are preserved:

python
gazu.task.update_task_data(task, {"render_layer": "bg"})

Using Metadata Descriptors ​

Meta columns allow you to attach structured data to assets, shots, and tasks. Common use cases include:

  • Technical specifications
  • Pipeline flags
  • External IDs
  • Delivery requirements

You can then visualize the metadata in the Kitsu dashboard or by reading the metadata field of an entity.

Reading and Writing Metadata via the API ​

Writing metadata to an asset:

python
gazu.asset.new_asset(
    project,
    asset_type,
    name,
    description=None,
    extra_data={},
    episode=None,
    is_shared=False
)

4. Managing your production list ​

Get a project ​

python
project = gazu.project.get_project(project_id)
project = gazu.project.get_project_by_name(name="Agent 327")

List all projects ​

python
projects = gazu.project.all_projects()

List all active projects ​

python
projects = gazu.project.all_open_projects()

Next Steps ​

Once a production is structured and configured, you can move on to people and permissions.