Bazaar API for AI Agents

npm install -g bazaar.it

# baz CLI — Mandatory Video Generation Workflow

Use this skill when the user wants to create, edit, or export videos using the Bazaar CLI (`baz`).

**This is a GATED workflow.** You MUST complete each phase in order. Do NOT skip phases. Do NOT declare "done" until the completion checklist at the bottom passes.

---

## Getting Started (New Agents)

If you don't have a Bazaar account or API key yet, register programmatically:

```bash
# 1. Discover what Bazaar can do
curl https://bazaar.it/api/v1/capabilities

# 2. Register (one POST, no human needed)
curl -X POST https://bazaar.it/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"email":"your-agent@example.com","name":"My Agent"}'
# Returns: api_key, auth header name, quickstart steps, endpoint URLs

# 3. Save your API key — authenticate all future requests with:
#    -H "x-api-key: <your-api-key>"

# 4. Check pricing before you start
curl https://bazaar.it/api/v1/pricing

# 5. Install the CLI
npm install -g bazaar.it
baz auth login <your-api-key>
```

**Balance starts at $0.** When you hit a paid operation, you'll get HTTP 402 with a `top_up_url` in the response body. Call `POST /api/v1/top-up` with `{"amount_cents": 500}` (minimum $5) to get a Stripe checkout URL.

**Shortcut:** If your human creates an account at bazaar.it, they get $4 to start with. Ask them to grab an API key from the dashboard and you can skip straight to step 5.

Already have an API key? Skip to Phase 1.

---

## When to Use

- User asks to create, edit, or export videos via CLI
- User wants to automate video generation
- User mentions "baz", "bazaar CLI", or "video generation from terminal"

## When to Use `baz prompt`

- **`baz prompt`** — All generation flows (scenes, voiceovers, AI video, avatars, URL-to-video)
- Use spar mode when you want planning-first conversation before execution

---

## Phase 1: Context (REQUIRED — do NOT skip)

You MUST set project context BEFORE generating any scenes. This gives the composition agent the information it needs to produce correct output on the first try.

### Minimum context required:
1. **Goal** — What is this video for? Who is the audience? What should they feel/do?
2. **Requirements** — Specific, verifiable things the video must contain
3. **Brand** — Colors, fonts, logo placement, visual style

```bash
# Create or select project
baz project create --name "Descriptive Name - Date/Purpose" --json
# OR
baz project use <id>

# Set goal (be specific — audience, purpose, desired outcome)
baz context add "Create 45-60 second feature announcement for [Product]. \
Audience: [who]. Key value: [what they get]." --label "goal"

# Add requirements (each one should be independently verifiable)
baz context add "Show [specific feature interaction]" --label "requirement"
baz context add "Include CTA: '[specific text]'" --label "requirement"
baz context add "Total duration: [range]" --label "requirement"

# Set brand guidelines
baz context add "Brand: [Name]. Primary [hex], accent [hex]. Font: [name]. \
[Logo placement]. [Visual style notes]." --label "brand"
```

### Verify context is set:
```bash
baz context list --json
```

**Gate:** Do NOT proceed to Phase 2 until `baz context list` shows at least one goal, one requirement, and one brand entry.

---

## Phase 2: Generate

Now prompt the agent to create scenes. You can use one big prompt or multiple scene-by-scene prompts.

```bash
# Option A: One comprehensive prompt
baz prompt "Create a video with: [scene 1 description], [scene 2], ..." --stream-json

# Option B: Scene-by-scene (more control)
baz prompt "Scene 1 (5s): Dark gradient intro, logo top-left, title slides up" --stream-json
baz prompt "Scene 2 (7s): Problem statement with mock UI..." --stream-json
baz prompt "Scene 3 (18s): Feature walkthrough..." --stream-json
```

Tips:
- Include duration in each prompt
- Be specific about animations, colors, layout
- Reference brand context set in Phase 1

---

## Phase 3: Review & Verify (REQUIRED — NEVER skip)

After generation, you MUST run both review and verify. This is not optional.

### Step 1: Review
```bash
baz review --json
```

Read the output. Compare every requirement from Phase 1 against what was generated.

### Step 2: Verify
```bash
baz verify --criteria "requirement 1,requirement 2,requirement 3" --json
```

Pass ALL requirements from Phase 1 as comma-separated criteria. The verify command checks each one.

### Interpret results:

```json
{
  "passedAll": true,   // ALL criteria met → proceed to Phase 5
  "passedAll": false,  // ANY criteria failed → MUST go to Phase 4
  "results": [
    { "criteria": "...", "passed": true },
    { "criteria": "...", "passed": false, "reason": "..." }
  ]
}
```

**Gate:** If `passedAll: false`, you MUST proceed to Phase 4. Do NOT export. Do NOT declare done.

---

## Phase 4: Iterate (REQUIRED if Phase 3 fails)

Fix every failing criteria. Then re-verify.

```
LOOP:
  1. Read failing criteria from Phase 3
  2. Fix with: baz prompt "Fix: [specific issue]" --stream-json
  3. Re-run: baz review --json
  4. Re-run: baz verify --criteria "req1,req2,req3" --json
  5. If passedAll: false → GOTO 1
  6. If passedAll: true → proceed to Phase 5
```

Do NOT exit this loop until `passedAll: true`.

---

## Phase 5: Export (only if requested)

Only export if the user explicitly asked for a rendered video AND Phase 3/4 passed.

```bash
baz export start --wait --json
```

---

## Command Quick Reference

| Command | Purpose |
|---------|---------|
| `baz project create --name "..." --json` | Create new project |
| `baz project use <id>` | Set active project |
| `baz context add "..." --label "goal"` | Set project goal |
| `baz context add "..." --label "requirement"` | Add verifiable requirement |
| `baz context add "..." --label "brand"` | Set brand guidelines |
| `baz context list --json` | View all context entries |
| `baz prompt "..." --stream-json` | Generate or edit scenes |
| `baz prompt "..." --stream-json` | Plan + execute with the agent (voiceover/music/video supported) |
| `baz review --json` | Get full project state for review |
| `baz verify --criteria "..." --json` | Verify specific criteria pass |
| `baz scenes list --json` | List all scenes |
| `baz export start --wait --json` | Render final video |

## Error Handling

| Category | Action |
|----------|--------|
| `transient` | Retry with backoff (wait `retry_after` seconds) |
| `validation` | Fix input, do not retry same request |
| `auth` | Check API key with `baz auth status` |
| `fatal` | Stop and report to user |

---

## Completion Checklist

You are NOT done until ALL of these are true:

- [ ] Phase 1: `baz context list` shows goal + requirements + brand
- [ ] Phase 2: Scenes generated via `baz prompt`
- [ ] Phase 3: `baz review --json` run AND `baz verify --criteria "req1,req2,..." --json` run
- [ ] Phase 4: `passedAll: true` (or was true on first verify)
- [ ] Phase 5: Export started (only if user requested it)

**If you skipped review/verify, you are not done. Go back and run them.**

## Web UI Access

Your human can also edit the project directly in the browser at:
`https://bazaar.it/projects/<project-id>/generate`

After creating a project, share this link so they can preview scenes, tweak code, or make manual edits alongside your CLI workflow.