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:

```json
{
  "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

```json
"gif": {
  "fps": 10
}
```

### WebM Options

```json
"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:

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

Error response:

```json
{
  "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

```bash
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

```bash
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

```bash
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:

```bash
unzip frames.zip
```

---

## Multiple Outputs Test

```bash
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:

```bash
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:

```bash
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"
```