---
name: alive-photos
description: >
  Turn a still photo into a living loop package the user owns (Alive Photos API).
  Use when the user wants an "alive" / living portrait / cinemagraph from a still,
  to cast or animate a photo for the web, or mentions Alive Photos / DynamicThumbs
  casting. Also use for /alive-photos. Do not hotlink Alive Photos in production —
  download the ZIP and host files in the project.
---

# Alive Photos

Factory, not CDN: **still → living loop ZIP → files live in the user's project**.

Base URL (local default): `http://127.0.0.1:8787`  
Full guide: `GET $BASE/agents.md` · OpenAPI: `GET $BASE/openapi.json` · Health: `GET $BASE/health`

## Auth

```http
Authorization: Bearer ap_live_...
```

Env: `ALIVE_API_KEY` or `ALIVE_PHOTOS_API_KEY`.

### No key yet — claim session (one human click)

```bash
curl -sS -X POST "$BASE/api/v1/agent/sessions" \
  -H "Content-Type: application/json" \
  -d '{"label":"agent","pack_id":"starter"}'   # pack_id optional
```

1. Show human `claim_url` (browser).
2. Poll `GET /api/v1/agent/sessions/{id}` with header `X-Agent-Session-Secret: {poll_secret}`.
3. On `status=ready`, store `api_key` once as `ALIVE_API_KEY`.

## Cast → download → wire

```bash
# Create (use Idempotency-Key)
curl -sS -X POST "$BASE/api/v1/jobs" \
  -H "Authorization: Bearer $ALIVE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@./photo.jpg" -F "title=Hero" -F "duration=6" \
  -F "prompt=Subtle living portrait, soft micro-motion only"

# Poll every 3–5s (casting often 1–4 minutes)
curl -sS -H "Authorization: Bearer $ALIVE_API_KEY" "$BASE/api/v1/jobs/$JOB_ID"

# Optional: paid revise / select best attempt
curl -sS -X POST "$BASE/api/v1/jobs/$JOB_ID/revise" \
  -H "Authorization: Bearer $ALIVE_API_KEY" \
  -F "prompt=Even softer motion" -F "resolution=480p"
curl -sS -X POST "$BASE/api/v1/jobs/$JOB_ID/select/2" \
  -H "Authorization: Bearer $ALIVE_API_KEY"

# Download selected package
curl -sS -L -o alive.zip -H "Authorization: Bearer $ALIVE_API_KEY" \
  "$BASE/api/v1/jobs/$JOB_ID/download"
unzip -o alive.zip -d ./public/media/
```

Wire **local** paths only:

```html
<video autoplay muted loop playsinline poster="/media/JOB-poster.jpg">
  <source src="/media/JOB-alive.mp4" type="video/mp4">
</video>
```

## Pricing (defaults)

**Every generation costs credits** (create + each revise).

| Gen | Credits |
|-----|---------|
| 480p 6s / 10s | 1 / 2 |
| 720p 6s / 10s | 2 / 4 |

Free trial: **1× 480p gen only**. Defaults: free/starter **480p**, pro/studio **720p**.  
Packs: starter 5/**$12** · pro 25/$39 · studio 100/**$159**.  
Quality refund: 50%, max 2/account, **not after download**. Extra API keys need paid plan.

On `402` → claim with `pack_id` or send human to `$BASE/app/billing`.  
On `demo_casts: true` in `/health` → server missing `XAI_API_KEY` (sample video).

## Do / don't

**Do:** claim → cast → poll → pick attempt → ZIP into repo → commit media.  
**Don't:** put API keys in HTML; hotlink production to Alive Photos; spam job create.