video_api_guide.md

Video Generation API Guide

This document explains how to use the video generation API endpoint to create animated outputs in GIF, WebM, or ZIP (PNG frames) format. It includes request structure, parameter explanations, and copy‑paste curl commands for testing.

---

Base Endpoint

https://cyjm1rsdzy6la31w.us-east-1.aws.endpoints.huggingface.cloud

---

Authentication

All requests require a Hugging Face access token.

Add this header to every request:

Authorization: Bearer YOUR_HF_TOKEN

---

Request Structure

Requests must be wrapped inside an "inputs" object:

{
  "inputs": {
    "prompt": "your prompt here",
    "outputs": ["gif"]
  }
}

---

Core Request Parameters

Parameter	Type	Default	Description
prompt	string	required	Text description of the video.
negative_prompt	string	""	What to avoid in the output.
num_frames	int	32	Total frames generated.
fps	int	12	Playback speed (GIF/WebM).
height	int	512	Frame height.
width	int	512	Frame width.
seed	int	null	Reproducibility.
outputs	array	["gif"]	Any of: "gif", "webm", "zip".
return_base64	bool	true	Returns base64 file data in JSON.
num_inference_steps	int	30	Quality vs speed tradeoff.
guidance_scale	float	7.5	Prompt adherence strength.

---

Output Configuration

GIF Options

"gif": {
  "fps": 10
}

WebM Options

"webm": {
  "fps": 24,
  "quality": "good"
}

Quality levels:

• "fast" — fastest encoding
• "good" — balanced (recommended)
• "best" — highest quality, slower

ZIP Output

ZIP always contains PNG frames:

frame_000000.png
frame_000001.png
...

---

Response Format

Successful response:

{
  "ok": true,
  "outputs": {
    "gif_base64": "...",
    "webm_base64": "...",
    "zip_base64": "..."
  }
}

Error response:

{
  "ok": false,
  "error": "message"
}

---

Best Practices

• Use jq -er when decoding base64 to prevent corrupted files
• Start with 16–32 frames for fast testing
• Use WebM for high quality playback
• Use ZIP when post‑processing frames externally

---

Example curl Commands

These commands save files directly without storing JSON.

Replace YOUR_HF_TOKEN.

---

GIF Test

curl -sS -X POST "https://cyjm1rsdzy6la31w.us-east-1.aws.endpoints.huggingface.cloud" \
  -H "Authorization: Bearer YOUR_HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "prompt": "cinematic sunset over mountains",
      "num_frames": 20,
      "fps": 10,
      "outputs": ["gif"]
    }
  }' \
| jq -er '.outputs.gif_base64' \
| base64 --decode > output.gif

---

WebM Test

curl -sS -X POST "https://cyjm1rsdzy6la31w.us-east-1.aws.endpoints.huggingface.cloud" \
  -H "Authorization: Bearer YOUR_HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "prompt": "drone flying through clouds",
      "num_frames": 32,
      "fps": 24,
      "outputs": ["webm"],
      "webm": { "quality": "good" }
    }
  }' \
| jq -er '.outputs.webm_base64' \
| base64 --decode > output.webm

---

ZIP Frames Test

curl -sS -X POST "https://cyjm1rsdzy6la31w.us-east-1.aws.endpoints.huggingface.cloud" \
  -H "Authorization: Bearer YOUR_HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "prompt": "ocean waves crashing",
      "num_frames": 16,
      "outputs": ["zip"]
    }
  }' \
| jq -er '.outputs.zip_base64' \
| base64 --decode > frames.zip

Unzip:

unzip frames.zip

---

Multiple Outputs Test

curl -sS -X POST "https://cyjm1rsdzy6la31w.us-east-1.aws.endpoints.huggingface.cloud" \
  -H "Authorization: Bearer YOUR_HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "prompt": "cinematic space nebula",
      "num_frames": 24,
      "fps": 12,
      "outputs": ["gif", "webm", "zip"],
      "webm": { "quality": "good" }
    }
  }' \
  -o response.json

Extract:

jq -er '.outputs.gif_base64' response.json | base64 --decode > output.gif
jq -er '.outputs.webm_base64' response.json | base64 --decode > output.webm
jq -er '.outputs.zip_base64' response.json | base64 --decode > frames.zip

---

Troubleshooting

Corrupted Files

Inspect JSON first:

jq . response.json

Ensure:

"ok": true

Large Outputs

Reduce:

• num_frames
• resolution

Or upload files to cloud storage and return a download URL.

---

Suggested Defaults

num_frames: 24–32
fps: 12 (GIF) / 24 (WebM)
resolution: 512x512
quality: "good"