Skip to main content

Peako Studio API Reference

Welcome to the complete Peako Studio API reference. This guide covers all endpoints available for building, managing, and rendering video templates programmatically.

Base URL​

https://peako.shin0x.space

Authentication​

All API requests require authentication via one of these methods:

API Key (Service-to-Service)​

Include the X-API-Key header:

curl -H "X-API-Key: YOUR_API_KEY" https://peako.shin0x.space/api/templates

Include the peako_session cookie:

curl -b "peako_session=YOUR_SESSION_TOKEN" https://peako.shin0x.space/api/templates
note

Session tokens are set by the OAuth flow and are httpOnly, Secure, and SameSite=Lax. Tokens expire after 7 days.

Key Concepts​

Templates​

Video templates are block-based compositions that define the structure of your video. Each template contains:

  • Tracks — layers for video, audio, text, or stickers
  • Blocks — fillable content placeholders (video, text, subtitles, audio, images)
  • Transforms — positioning and sizing (using normalized coordinates 0.0–1.0)
  • Effects & Transitions — visual enhancements

Blocks​

Blocks are fillable placeholders in your template. You fill them at render time with content (videos, images, text, captions, etc.). Each block has:

  • A blockId (unique within the template)
  • A type (video, image, text, subtitle, audio)
  • A required flag (must be filled at render, or optional)
  • A durationMode that controls how the block's duration is calculated

Render Workflow​

  1. Create a template with your desired structure and blocks
  2. Fill the blocks at render time with content
  3. Choose output format (mp4, webm, mov) and delivery mode
  4. Monitor the job via polling or webhook
  5. Download or process the rendered video

API Sections​

  • Authentication — OAuth flow, login, logout, API keys
  • Assets — Upload media files and subtitle files to the CDN
  • Templates — Create, list, retrieve, update, delete templates
  • Rendering — The core feature — render templates with block fills (with deep detail on subtitle/transcription)
  • Subtitles & Transcription — Subtitle parsing, transcription workflows
  • Jobs — Poll job status, cancel jobs, list jobs
  • Video Operations — Trim, merge, mute, add audio, blur, speed-ramp
  • Effects & Transitions — Browse available effects and transitions
  • System — Health check, error codes, rate limits

Rate Limits​

  • Authenticated requests: 100 requests per minute
  • Unauthenticated requests: 10 requests per minute

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 85
X-RateLimit-Reset: 1709852843

If you exceed the limit, you'll receive a 429 Too Many Requests response.

Error Handling​

All errors follow this format:

{
  "status": 400,
  "code": "INVALID_REQUEST",
  "message": "Field 'blockId' is required",
  "details": {
    "field": "blockId"
  }
}

Common HTTP status codes:

  • 200 — Success
  • 201 — Created
  • 202 — Accepted (async job queued)
  • 400 — Bad request (validation error)
  • 401 — Unauthorized (missing/invalid credentials)
  • 404 — Not found
  • 409 — Conflict (e.g., can't cancel an active job)
  • 429 — Too many requests (rate limited)
  • 500 — Server error

Best Practices​

  1. Use async rendering (delivery: "async") for anything longer than a few seconds
  2. Poll job status with exponential backoff (2–5 seconds initially, up to 30 seconds)
  3. Upload assets once, then reference them by URL across multiple render requests
  4. Test with simple templates first before complex multi-track compositions
  5. Validate your template structure with GET /api/templates/:id to inspect blockSchema before rendering
  6. Pre-transcribe when you can — if you already have captions, use the captions array instead of auto_transcribe

Ready to dive in? Start with Authentication.