This quickstart uses the managed `/clips` workflow. It handles source ingest, transcription, short suggestion selection, vertical layout, captions, QA, and export through one state machine.

## 1. Get An API Key [#1-get-an-api-key]

Create a live API key in your workspace:

**Dashboard → Workspace → AI → API Keys**

Only workspace owners/admins can create keys.

```bash title="Terminal"
export BLITZREELS_API_KEY="br_live_..."

curl https://blitzreels.com/api/v1/auth/validate \
  -H "Authorization: Bearer $BLITZREELS_API_KEY"
```

## 2. Create A Clip [#2-create-a-clip]

Start with a YouTube source:

```bash title="Terminal"
CLIP=$(curl -s -X POST https://blitzreels.com/api/v1/clips \
  -H "Authorization: Bearer $BLITZREELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "Demo short",
    "source": {
      "source_type": "youtube",
      "youtube_url": "https://www.youtube.com/watch?v=VIDEO_ID"
    },
    "selection": {
      "selection_mode": "auto_best"
    },
    "target": {
      "aspect_ratio": "9:16",
      "min_duration_seconds": 8,
      "max_duration_seconds": 45
    },
    "layout": {
      "layout_mode": "auto",
      "content_type_hint": "auto"
    },
    "captions": {
      "enabled": true
    },
    "qa": {
      "qa_mode": "permissive"
    },
    "export": {
      "auto_export": false
    }
  }')

CLIP_ID=$(echo "$CLIP" | jq -r '.clip.clip_id')
```

If the source is already in your workspace media library, send `"source_type": "asset"` with `"asset_id": "MEDIA_ASSET_ID"` instead of `youtube_url`.

## 3. Poll Until Action Is Needed [#3-poll-until-action-is-needed]

```bash title="Terminal"
curl https://blitzreels.com/api/v1/clips/$CLIP_ID \
  -H "Authorization: Bearer $BLITZREELS_API_KEY"
```

Follow `clip.next_action`:

* `poll` means keep polling.
* `reselect` means choose a different suggestion or provide a time range.
* `repair` means run one repair pass.
* `export` means the clip is ready to render.
* `stop` means the workflow is finished or failed.

## 4. Reselect Or Repair If Needed [#4-reselect-or-repair-if-needed]

Choose a specific suggestion:

```bash title="Terminal"
curl -X POST https://blitzreels.com/api/v1/clips/$CLIP_ID/reselect \
  -H "Authorization: Bearer $BLITZREELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "selection": {
      "selection_mode": "suggestion",
      "suggestion_id": "SUGGESTION_ID"
    }
  }'
```

Or run a repair pass:

```bash title="Terminal"
curl -X POST https://blitzreels.com/api/v1/clips/$CLIP_ID/repair \
  -H "Authorization: Bearer $BLITZREELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repair_mode":"auto"}'
```

## 5. Export [#5-export]

When `next_action` is `export`:

```bash title="Terminal"
curl -X POST https://blitzreels.com/api/v1/clips/$CLIP_ID/export \
  -H "Authorization: Bearer $BLITZREELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resolution": "1080p",
    "format": "mp4"
  }'
```

Poll the clip again until `clip.export.status` is `ready`, then use `clip.export.download_url`.

## CLI Shortcut [#cli-shortcut]

The same flow is available from the CLI:

```bash title="Terminal"
blitzreels clips create \
  --source-type youtube \
  --youtube-url "https://www.youtube.com/watch?v=VIDEO_ID" \
  --name "Demo short" \
  --min-duration 8 \
  --max-duration 45 \
  --qa-mode permissive \
  --json

blitzreels clips wait --clip-id CLIP_ID --json
blitzreels clips export --clip-id CLIP_ID --resolution 1080p --format mp4
```

## Next Steps [#next-steps]

* [CLI](/docs/cli)
* [AI Agent Bootstrap](/docs/agents)
* [Agent Skills Repository](/docs/agent-skills-repo)
* [Clipping API](/docs/clipping)
* [API Reference](/docs/reference)