Storage (Hippius S3)

Leoma uses Hippius S3–compatible storage for source videos and sample artifacts. This page summarizes how it’s used and how to work with it; for full S3 API details see Hippius S3 API.

Overview

• Source bucket (videos): Holds the corpus of real clips (and optionally first frames) used to create tasks. Validators/samplers read from here; corpus ingestion may write new videos here.

• Samples bucket: Holds per-task, per-miner artifacts: first frame, original clip, generated videos, and (optionally) evaluation result JSON. The Leoma API and validators read/write here; the dashboard can use presigned URLs to display media without exposing credentials.

Buckets and keys

• Source bucket (e.g. videos): Configurable via HIPPIUS_SOURCE_BUCKET. Objects are keyed by the ingestion/corpus logic (e.g. path or prefix).

• Samples bucket (e.g. samples): Configurable via HIPPIUS_SAMPLES_BUCKET. Typical layout:

  • {task_id}/first_frame.png — first frame image for the task

  • {task_id}/original_clip.mp4 — real clip used for evaluation

  • {task_id}/generated_videos/{miner_hotkey}.mp4 — miner’s generated video

  • {task_id}/evaluation_results/{validator_hotkey}.json — canonical evaluation payload (and optional signature) uploaded by the API after sample submission

Credentials (environment)

The Leoma api uses access-key authentication (not seed phrases). Separate keys can be used for:

• Videos bucket: read (sampler), write (corpus ingest). Env: HIPPIUS_VIDEOS_READ_ACCESS_KEY, HIPPIUS_VIDEOS_READ_SECRET_KEY, HIPPIUS_VIDEOS_WRITE_ACCESS_KEY, HIPPIUS_VIDEOS_WRITE_SECRET_KEY.

• Samples bucket: read (optional; can fall back to write), write (API uploads). Env: HIPPIUS_SAMPLES_READ_ACCESS_KEY, HIPPIUS_SAMPLES_READ_SECRET_KEY, HIPPIUS_SAMPLES_WRITE_ACCESS_KEY, HIPPIUS_SAMPLES_WRITE_SECRET_KEY.

Endpoint and region are set via HIPPIUS_ENDPOINT (e.g. s3.hippius.com) and HIPPIUS_REGION (e.g. decentralized).

Presigned URLs

The task-miner detail endpoint (GET /tasks/{task_id}/miner/{miner_hotkey}) can return presigned GET URLs for first frame, original clip, and generated video so the dashboard can display them without exposing S3 credentials. These are generated using the api’s read credentials and short expiry.

Best practices (Hippius)

• Bucket naming: Lowercase letters, numbers, hyphens only.

• Large files: Use multipart uploads for files > 5MB.

• Security: Never expose secret keys in client-side code; use presigned URLs for read-only access in the app.

• Rate limits: See Hippius S3 (e.g. 100 req/min per account).

References

• Hippius S3 API – User Guide

• Hippius – Getting Started, Authentication, Supported Operations