RunUGC
Start creating →

Documentation / v1

Build and automate with RunUGC

Setup, CLI, and API reference.

Node.js 20+CLI and API v1OpenAPI 3.1

01 / Quickstart

Onboard an agent and generate a slideshow

Give this sequence to an agent. It installs the public CLI, asks the human to sign in and pay when needed, then creates and returns the generated campaign assets.

Prerequisites

Use Node.js 20 or newer with npm and npx available. A creative brief is stored as a reusable campaign template, so CLI commands pass its numeric id through --template.

1. Provision credentials

The human completes Google sign-in. The CLI saves the API base URL, organization id, workspace id, template id, and API key locally.

npx @runugc/cli provision new
npx @runugc/cli provision status --json
  • Read ids from context defaults --json or provision status --json unless the human supplies different ids.

2. Buy a token pack

Use --no-open when the agent should print a Stripe URL for the human instead of opening a browser.

npx @runugc/cli pricing list --json
npx @runugc/cli billing checkout --pack pack-5k --no-open
npx @runugc/cli wallet show --json

3. Estimate and create the run

Runs debit the organization wallet. A low balance returns 402 with insufficient_balance; fund the wallet, confirm the new balance, then retry.

npx @runugc/cli brief list --workspace <workspace-id> --json
npx @runugc/cli run estimate --workspace <workspace-id> --template <brief-id> --json
npx @runugc/cli run create --workspace <workspace-id> --template <brief-id> --idempotency-key <stable-key> --json
npx @runugc/cli run status --run <run-id> --json

4. Wait and inspect artifacts

The numeric runId returned by create works with every later run command. Internal UUIDs are labeled workflowRunId. Return the run id, final status, artifact metadata, and downloaded ZIP path to the human.

# Or submit and wait in one command
npx @runugc/cli run create --workspace <workspace-id> --template <brief-id> --idempotency-key <stable-key> --sync --json

npx @runugc/cli run wait --run <run-id> --timeout 600 --interval 10 --json
npx @runugc/cli run artifacts --run <run-id> --json
npx @runugc/cli run download --run <run-id> --json

02 / Authentication

Sign in once, then let the agent continue

The saved credentials flow keeps later commands moving without asking the human to find and paste account identifiers.

Commands

Environment variables also work for hosted or scripted setups. Prefer saved credentials during user onboarding.

npx @runugc/cli provision new
npx @runugc/cli provision status --json

Agent rules

  • Use provision status --json to read ids instead of asking the human to find them manually.
  • Use scoped API keys or grants for long-running agents instead of sharing a broad human key.
  • Keep V1_REQUIRE_API_KEY=true in production so v1 routes require Bearer auth.
  • provision status masks the secret and is safe to log.

03 / Billing

Buy tokens before creating runs

Check pricing, create a checkout URL for a token pack, hand it to the human payer, and confirm wallet balance before generation.

Commands

npx @runugc/cli pricing list --json
npx @runugc/cli billing checkout --pack pack-5k --no-open
npx @runugc/cli billing status --json
npx @runugc/cli wallet show --json
  • Do not create runs after an insufficient-balance response.
  • Always start checkout with an explicit pack id, such as pack-5k.
  • After payment, run wallet show before retrying generation.

Local development

Set CLANKER_UGC_DEV_MODE=true for local CLI testing. Checkout then credits the seeded wallet directly without calling Stripe. This mode is ignored in production.

04 / Run lifecycle

Estimate, create, wait, then inspect artifacts

Runs spend wallet tokens. Estimate first, submit with a stable idempotency key, then poll with the returned run id or use sync mode.

Commands

cat brief.md | npx @runugc/cli brief create --workspace <workspace-id> --name <name> --text-stdin --json
npx @runugc/cli brief list --workspace <workspace-id> --json
npx @runugc/cli run estimate --workspace <workspace-id> --template <brief-id> --json
npx @runugc/cli run create --workspace <workspace-id> --template <brief-id> --idempotency-key <stable-key> --json
cat campaign-notes.md | npx @runugc/cli run create --workspace <workspace-id> --template <brief-id> --idempotency-key <stable-key> --instructions-stdin --json
npx @runugc/cli run status --run <run-id> --json
npx @runugc/cli run wait --run <run-id> --timeout 600 --interval 10 --json
npx @runugc/cli run artifacts --run <run-id> --json
npx @runugc/cli run download --run <run-id> --json

Agent rules

  • Use the workspace and brief ids from context defaults or provision status unless the human provides different ids.
  • Use a deterministic idempotency key when retrying the same create request.
  • Pipe one-off direction through --instructions-stdin instead of editing a reusable template.
  • Use the numeric runId for status, wait, artifacts, and download. UUIDs are labeled workflowRunId.
  • Status and wait are compact by default. Add --verbose when diagnosing workflow steps or artifacts.
  • Exit code 2 means the wait timed out; the submission may still be running.
  • TikTok and YouTube publishing require --video-url or an existing video artifact.
  • Use run artifacts for metadata and run download for the authenticated ZIP.

05 / CLI reference

Commands agents can follow

Use the exact package name npx @runugc/cli .... The CLI saves local credentials and supports JSON output for agent-readable results.

Command index

npx @runugc/cli provision new

Ask the human to sign in and save credentials for future commands.

npx @runugc/cli provision status --json

Read the saved base URL, organization, workspace, template, and masked key.

npx @runugc/cli context defaults --json

Show the default organization, workspace, and template ids.

npx @runugc/cli onboarding init --workspace <workspace-id> --site-url <url> --json

Extract homepage context from a website and save onboarding answers.

npx @runugc/cli onboarding update --workspace <workspace-id> --answers-json ./fixtures/onboarding.json --json

Update brand, product, and audience context from a JSON file.

npx @runugc/cli pricing list --json

List available token packs before asking the human to pay.

npx @runugc/cli billing checkout --pack pack-5k --no-open

Create a Stripe-hosted token-pack checkout URL for the human payer.

npx @runugc/cli wallet show --json

Check token balance before creating or retrying a run.

cat brief.md | npx @runugc/cli brief create --workspace <workspace-id> --name <name> --text-stdin --json

Create a reusable creative brief template.

npx @runugc/cli brief list --workspace <workspace-id> --json

List creative briefs and choose the id to pass as --template.

npx @runugc/cli run estimate --workspace <workspace-id> --template <brief-id> --json

Get a token estimate before starting a run.

npx @runugc/cli run create --workspace <workspace-id> --template <brief-id> --idempotency-key <key> --json

Async mode: submit a run and get its numeric runId immediately.

npx @runugc/cli run create --workspace <workspace-id> --template <brief-id> --idempotency-key <key> --sync --json

Sync mode: submit, poll every 10 seconds, and return when ready.

npx @runugc/cli run status --run <run-id> --json

Query compact status for an async run; add --verbose for internals.

npx @runugc/cli run artifacts --run <run-id> --json

Return generated artifact metadata and the download endpoint.

cat campaign-notes.md | npx @runugc/cli run create --workspace <workspace-id> --template <brief-id> --idempotency-key <key> --instructions-stdin --json

Pass one-off creative direction through stdin.

npx @runugc/cli run download --run <run-id> --json

Download the authenticated ZIP bundle to ./run-<id>.zip by default.

CLI conventions

  • Use --json for machine-readable output.
  • Use --no-open on checkout when the agent should hand a URL to a human.
  • Estimate before creating runs and pass a stable idempotency key.
  • Use async mode when the caller will poll later; use --sync when the caller should block.
  • Use run download instead of inventing or scraping artifact URLs.

06 / API overview

API details for agent implementers

Use the CLI for normal onboarding and generation. Call the API directly when building a wrapper or inspecting exact request and response contracts.

Endpoint index

Runs

  • POST /api/v1/runs/estimate
  • POST /api/v1/runs
  • GET /api/v1/runs/{id}
  • GET /api/v1/runs/{id}/artifacts
  • GET /api/v1/runs/{id}/download

Storyboards

  • GET /api/v1/storyboards
  • POST /api/v1/storyboards
  • GET /api/v1/storyboards/{id}
  • POST /api/v1/storyboards/{id}/approve

Creative briefs

  • GET /api/v1/creative-briefs
  • POST /api/v1/creative-briefs
  • GET /api/v1/creative-briefs/{id}
  • PATCH /api/v1/creative-briefs/{id}
  • DELETE /api/v1/creative-briefs/{id}

Billing and auth

  • GET /api/v1/wallet
  • GET /api/v1/pricing
  • POST /api/v1/api-keys
  • POST /api/v1/agent-grants
  • GET /api/v1/webhooks
  • POST /api/v1/webhooks

OpenAPI document

This endpoint returns the current OpenAPI 3.1 document for direct API clients.

GET /api/v1/openapi