Preview Files - Zou (Kitsu API)

Overview

Preview files are media files (images, videos, or other formats) attached to tasks for review and feedback. They support automatic thumbnail generation, video normalization, annotations, and multiple revisions per task.

Preview File Model

Preview files contain the following key properties:

id: Unique identifier (UUID)
task_id: Associated task
revision: Version number
position: Order within revision
name: Display name
original_name: Original filename
extension: File type (mp4, png, etc.)
status: Processing status (processing, ready, broken)
source: Upload source (webgui, api, etc.)
file_size: Size in bytes
width: Image/video width in pixels
height: Image/video height in pixels
duration: Video duration in seconds
annotations: Review annotations array
person_id: Uploader
created_at: Upload timestamp
updated_at: Last modification timestamp

Supported Formats

Pictures

Supported extensions: jpg, jpeg, jpe, png

Automatic thumbnail generation (square and rectangle)
Original resolution preserved
Multiple size variants created

Movies

Supported extensions: mp4, mov, avi, mkv, webm, m4v, wmv

Normalized to MP4 format
Automatic thumbnail extraction
Tile generation for scrubbing
Low-def version for faster streaming

Other Files

Supported extensions: pdf, psd, psb, ai, blend, ma, mb, hip, fbx, obj, glb, gltf, svg, exr, and more

Stored as-is without processing
Direct download available

Source: zou/app/blueprints/previews/resources.py:44-88

Upload Preview Files

Create Preview File Entry

First, create a preview file entry via comment:

POST /api/actions/tasks/{task_id}/batch-comment

Request: Multipart form data

import requests

# Prepare comment data with preview
comments_data = [
    {
        "text": "Updated character animation",
        "task_status_id": task_status_id
    }
]

files = {
    "comments": (None, json.dumps(comments_data)),
    "preview_file-0-0": open("animation.mp4", "rb")
}

response = requests.post(
    f"{base_url}/api/actions/tasks/{task_id}/batch-comment",
    files=files,
    headers={"Authorization": f"Bearer {token}"}
)

Source: zou/app/blueprints/previews/resources.py:555-599

Upload to Existing Preview

Upload file content to an existing preview entry:

POST /pictures/preview-files/{preview_file_id}

Request: Multipart form data with file

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@preview.mp4" \
  "https://kitsu.example.com/pictures/preview-files/{preview_file_id}"

Query Parameters:

normalize (optional): Enable video normalization (default: true)

Source: zou/app/blueprints/previews/resources.py:376-437

Download Preview Files

Get Preview Movie

Download the normalized MP4 video:

GET /movies/originals/preview-files/{preview_file_id}.mp4

Response: Video file with caching headers Source: zou/app/blueprints/previews/resources.py:658-700

Get Low-Def Movie

Download low-definition version for streaming:

GET /movies/low/preview-files/{preview_file_id}.mp4

Falls back to full quality if low-def not available. Source: zou/app/blueprints/previews/resources.py:703-751

Download as Attachment

Force download with original filename:

GET /movies/originals/preview-files/{preview_file_id}/download

Source: zou/app/blueprints/previews/resources.py:754-798

Get Preview Image

Download image preview:

GET /pictures/originals/preview-files/{preview_file_id}.{extension}

Supported extensions: png, pdf, etc. Source: zou/app/blueprints/previews/resources.py:801-865

Thumbnails

Rectangle Thumbnail

Get standard thumbnail (optimized for 16:9 aspect ratio):

GET /pictures/thumbnails/preview-files/{preview_file_id}.png

Source: zou/app/blueprints/previews/resources.py:1086-1089

Square Thumbnail

Get square thumbnail (for avatars, cards):

GET /pictures/thumbnails-square/preview-files/{preview_file_id}.png

Source: zou/app/blueprints/previews/resources.py:1106-1108

Original Resolution

Get full-resolution preview image:

GET /pictures/originals/preview-files/{preview_file_id}.png

Source: zou/app/blueprints/previews/resources.py:1111-1113

Preview Size

Get medium-resolution preview:

GET /pictures/previews/preview-files/{preview_file_id}.png

Source: zou/app/blueprints/previews/resources.py:1097-1103

Tile Preview

Get tile sprite for video scrubbing:

GET /movies/tiles/preview-files/{preview_file_id}.png

Source: zou/app/blueprints/previews/resources.py:1092-1094

Preview Management

Set as Main Preview

Set a preview as the entity’s main preview:

PUT /api/actions/preview-files/{preview_file_id}/set-main-preview

Query Parameters:

frame_number (optional): Extract specific frame from movie

Request Body:

{
  "frame_number": 120  // Optional: for movie previews
}

Response:

{
  "id": "entity-id",
  "preview_file_id": "preview-file-id"
}

Source: zou/app/blueprints/previews/resources.py:1329-1399

Update Preview Position

Change the order of previews within a revision:

PUT /api/actions/preview-files/{preview_file_id}/update-position

Request Body:

{
  "position": 2
}

Source: zou/app/blueprints/previews/resources.py:1402-1458

Delete Preview File

Use the deletion service to remove a preview:

from zou.app.services import deletion_service

deletion_service.remove_preview_file_by_id(preview_file_id)

Source: zou/app/services/files_service.py:890-899

Annotations

Update Annotations

Add, update, or delete annotations on a preview:

PUT /api/actions/preview-files/{preview_file_id}/update-annotations

Request Body:

{
  "additions": [
    {
      "time": 0,
      "drawing": {
        "objects": [
          {
            "type": "path",
            "x": 100,
            "y": 200,
            "color": "#FF0000"
          }
        ]
      }
    }
  ],
  "updates": [
    {
      "time": 0,
      "drawing": {
        "objects": [
          {
            "id": "annotation-id",
            "x": 150,
            "y": 250
          }
        ]
      }
    }
  ],
  "deletions": [
    {
      "time": 0,
      "objects": ["annotation-id-to-delete"]
    }
  ]
}

Response: Updated preview file with annotations Source: zou/app/blueprints/previews/resources.py:1461-1562

Annotation Format

Annotations are stored as an array of time-based drawings:

[
  {
    "time": 0,  // Frame number or timestamp
    "drawing": {
      "objects": [
        {
          "id": "uuid",
          "type": "path",
          "x": 100,
          "y": 200,
          "color": "#FF0000"
        }
      ]
    }
  }
]

Source: zou/app/services/preview_files_service.py:413-579

Video Processing

Normalization

Videos are automatically normalized to:

Format: MP4 (H.264)
Resolution: Project or entity resolution (default: 1080p height)
Frame rate: Project or entity FPS (default: 25.00)
Variants: Full quality + low-def version

Source: zou/app/services/preview_files_service.py:185-336

Processing Status

Preview files have three statuses:

processing: Video is being normalized
ready: File is ready for viewing
broken: Processing failed

Check status before displaying:

preview_file = files_service.get_preview_file(preview_file_id)
if preview_file["status"] == "ready":
    # Display preview
else:
    # Show processing indicator

Background Processing

When job queue is enabled, video normalization happens asynchronously:

# Upload returns immediately, processing happens in background
queue_store.job_queue.enqueue(
    preview_files_service.prepare_and_store_movie,
    args=(preview_file_id, uploaded_movie_path, True),
    job_timeout=int(config.JOB_QUEUE_TIMEOUT)
)

Source: zou/app/blueprints/previews/resources.py:241-270

Advanced Features

Extract Frame from Movie

Extract a specific frame from a video:

GET /api/actions/preview-files/{preview_file_id}/extract-frame?frame_number=120

Query Parameters:

frame_number (optional): Frame to extract (default: 0)

Response: PNG image of the frame Source: zou/app/blueprints/previews/resources.py:1637-1694

Extract Tile

Generate or retrieve tile sprite for scrubbing:

GET /api/actions/preview-files/{preview_file_id}/extract-tile

Response: Tile sprite PNG Source: zou/app/blueprints/previews/resources.py:1697-1743

Running Preview Files

Get all previews currently processing or broken:

GET /api/data/playlists/preview-files/running

Query Parameters:

cursor_preview_file_id (optional): Pagination cursor
limit (optional): Max results per page

Response:

[
  {
    "id": "preview-file-id",
    "status": "processing",
    "project_id": "project-id",
    "task_type_id": "task-type-id",
    "full_entity_name": "Asset > Character > Hero"
  }
]

Source: zou/app/blueprints/previews/resources.py:1565-1634

Preview Background Files

Upload HDR Background

Upload an HDR background for preview compositing:

POST /pictures/preview-background-files/{preview_background_file_id}

Request: Multipart form data with HDR file Supported extensions: hdr Source: zou/app/blueprints/previews/resources.py:1746-1913

Get Background File

Download preview background:

GET /pictures/preview-background-files/{preview_background_file_id}.{extension}

Source: zou/app/blueprints/previews/resources.py:1915-1977

Get Background Thumbnail

Get thumbnail of background file:

GET /pictures/thumbnails/preview-background-files/{preview_background_file_id}.png

Source: zou/app/blueprints/previews/resources.py:1980-1993

Best Practices

Revision Management

Preview revisions match comment revisions
Multiple previews can be in one revision
Use position to order previews within revision

Video Upload

Enable normalization for consistent playback
Wait for status=ready before displaying
Use low-def version for faster streaming
Check file_size before upload for large files

Thumbnails

Use square thumbnails for cards and lists
Use rectangle thumbnails for preview strips
Thumbnails are auto-generated for images and videos
Cache thumbnail URLs client-side

Annotations

Store annotations at preview level, not comment
Use time-based keys for video annotations
Generate unique IDs for annotation objects
Use additions/updates/deletions for atomic changes

Example Workflow

import requests
import json

# 1. Create comment with preview
comments_data = [{
    "text": "Latest animation review",
    "task_status_id": task_status_id
}]

files = {
    "comments": (None, json.dumps(comments_data)),
    "preview_file-0-0": open("animation.mp4", "rb")
}

response = requests.post(
    f"{base_url}/api/actions/tasks/{task_id}/batch-comment",
    files=files,
    headers={"Authorization": f"Bearer {token}"}
)

comment = response.json()[0]
preview_file = comment["preview_files"][0]

# 2. Wait for processing (in real app, poll or use websockets)
while True:
    preview = requests.get(
        f"{base_url}/api/data/preview-files/{preview_file['id']}",
        headers={"Authorization": f"Bearer {token}"}
    ).json()
    
    if preview["status"] == "ready":
        break
    elif preview["status"] == "broken":
        raise Exception("Preview processing failed")
    
    time.sleep(2)

# 3. Add annotations
requests.put(
    f"{base_url}/api/actions/preview-files/{preview_file['id']}/update-annotations",
    json={
        "additions": [{
            "time": 120,
            "drawing": {
                "objects": [{
                    "type": "text",
                    "text": "Fix this pose",
                    "x": 100,
                    "y": 200
                }]
            }
        }]
    },
    headers={"Authorization": f"Bearer {token}"}
)

# 4. Set as entity main preview
requests.put(
    f"{base_url}/api/actions/preview-files/{preview_file['id']}/set-main-preview",
    json={"frame_number": 120},
    headers={"Authorization": f"Bearer {token}"}
)

Comments - Adding comments with previews
Tasks - Task review workflow
Working Files - Source files

​Overview

​Preview File Model

​Supported Formats

​Pictures

​Movies

​Other Files

​Upload Preview Files

​Create Preview File Entry

​Upload to Existing Preview

​Download Preview Files

​Get Preview Movie

​Get Low-Def Movie

​Download as Attachment

​Get Preview Image

​Thumbnails

​Rectangle Thumbnail

​Square Thumbnail

​Original Resolution

​Preview Size

​Tile Preview

​Preview Management

​Set as Main Preview

​Update Preview Position

​Delete Preview File

​Annotations

​Update Annotations

​Annotation Format

​Video Processing

​Normalization

​Processing Status

​Background Processing

​Advanced Features

​Extract Frame from Movie

​Extract Tile

​Running Preview Files

​Preview Background Files

​Upload HDR Background

​Get Background File

​Get Background Thumbnail

​Best Practices

​Revision Management

​Video Upload

​Thumbnails

​Annotations

​Example Workflow

​Related Resources

Overview

Preview File Model

Supported Formats

Pictures

Movies

Other Files

Upload Preview Files

Create Preview File Entry

Upload to Existing Preview

Download Preview Files

Get Preview Movie

Get Low-Def Movie

Download as Attachment

Get Preview Image

Thumbnails

Rectangle Thumbnail

Square Thumbnail

Original Resolution

Preview Size

Tile Preview

Preview Management

Set as Main Preview

Update Preview Position

Delete Preview File

Annotations

Update Annotations

Annotation Format

Video Processing

Normalization

Processing Status

Background Processing

Advanced Features

Extract Frame from Movie

Extract Tile

Running Preview Files

Preview Background Files

Upload HDR Background

Get Background File

Get Background Thumbnail

Best Practices

Revision Management

Video Upload

Thumbnails

Annotations

Example Workflow

Related Resources