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

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


**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` vs Spar

- **Direct `baz prompt`** — Scene creation, edits, full agent orchestration
- **`baz prompt --spar`** — Planning-only conversation (no timeline mutations)

---

## 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:

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.

# 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

Choreography (REQUIRED for 3+ scene videos)

For videos with 3 or more scenes, plan choreography BEFORE generating. This prevents the "lockstep slideshow" pattern where all layers swap at the same frame boundary.

Actor Planning Template

Before prompting, plan your actors:

Actor	Track	Lifetime	Role
Background	0	Full duration	Evolving gradient, particles
Hero	1	60-80%	Main UI, enters, demotes to corner, returns
Supporting	1-2	20-40%	Cards/charts, appear during hero demotion
Text	2+	10-30%	Headlines, arrive at beat points, explicit exits

5 Prompt Enrichment Rules

Every content prompt includes exit instructions (exempt: persistent backgrounds, final CTA)
Prefer ONE background on Track 0 for the full video duration
Every overlay prompt includes position and size — scenes that share screen time must not share screen space
Specify spring animation for hero elements (spring() for hero entrance)
Include energy level hints in prompts ("high energy entrance", "calm sustained section")

GOOD Example — context injection + one natural prompt:

baz context add "CHOREOGRAPHY: Every overlay scene must specify its position and size. \
  Use spring() for hero elements. Every non-final scene must have exit animations. \
  Prefer one continuous background." --label "instructions"

baz prompt "Create a 15-second product demo: dark theme intro with logo, \
  feature showcase with 3 cards, area chart showing growth, and a CTA. \
  Brand: #6366f1 purple, #10b981 green, Inter font." --stream-json

ONE natural prompt. The composition agent handles decomposition into tracks + spatial layout internally based on choreography context.

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

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

Step 1: Review

baz review --json

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

Step 2: Verify

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:

{
  "passedAll": true,
  "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.

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 "..." --spar`	Planning-only conversation (no edits)
`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.

External Endpoints

URL	Method	Data Sent	Purpose
`bazaar.it/api/v1/capabilities`	GET	None	Discover available tools
`bazaar.it/api/v1/register`	POST	email, name	Create agent account
`bazaar.it/api/v1/pricing`	GET	None	View operation costs
`bazaar.it/api/v1/estimate`	POST	operation keys + quantities	Pre-execution cost estimate
`bazaar.it/api/v1/top-up`	POST	amount in cents	Get Stripe checkout URL
`bazaar.it/api/generate-stream`	POST	prompt, projectId	Generate video scenes (SSE)
`bazaar.it/api/trpc/*`	POST	varies	Project CRUD, scene management

Security & Privacy

Authentication: All non-discovery endpoints require x-api-key header
Data sent: Your prompts, project metadata, and scene code are sent to Bazaar servers for AI processing
Data stored: Projects, scenes, and generated assets are stored on Bazaar's infrastructure (Neon DB + Cloudflare R2)
No local file access: This skill only uses the baz CLI binary — it does not read or modify local files beyond CLI config at ~/.bazaar/config.json
Balance: Operations consume dollar balance. Check baz auth status to see remaining balance before large jobs
Exports: Rendered videos are stored on Bazaar CDN and accessible via URL

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.

baz

baz CLI — Mandatory Video Generation Workflow

Getting Started (New Agents)