# EzUGC API Documentation

Base URL: https://api.ezugc.ai

The EzUGC public API generates UGC-style video ads, any-model video, image ads, captions, and saved brands. Live contract:

https://api.ezugc.ai/openapi.json

## Authentication

Send a paid-account key on every functional request:

- `Authorization: Bearer ezk_live_...`, or
- `x-api-key: ezk_live_...`

Full walkthrough: https://www.ezugc.ai/docs/auth

## Paid subscription required

API keys are issued only from the EzUGC dashboard, and only for accounts on Startup, Growth, or Pro with an active paid subscription (from $99/month). There is no trial key, guest key, or anonymous generation route.
Every call to /api/public re-checks that the account is still paid. If you cancel or the subscription lapses, leftover keys start returning HTTP 402 PUBLIC_API_SUBSCRIPTION_REQUIRED. MCP tool calls use the same key and the same check.

## First call

```bash
curl -sS https://api.ezugc.ai/api/public/me \
  -H "Authorization: Bearer ezk_live_YOUR_KEY"
```

A 200 means the key is valid and the account is paid. A 401 means the key is missing, malformed, or revoked. A 402 means the account is no longer on an active paid plan.

## Endpoints

- `GET /api/public/me` — Account id, key prefix, scopes, payment status
- `GET /api/public/usage` — Billing-cycle video usage and remaining quota
- `GET /api/public/jobs` — List recent generation jobs
- `GET /api/public/jobs/{jobId}` — Poll one job until it completes
- `POST /api/public/ugc/jobs` — Queue a UGC video ad
- `GET /api/public/video/models` — List video models available to this key
- `POST /api/public/video/jobs` — Queue a video generation job
- `GET /api/public/image-ads/models` — List image models available to this key
- `POST /api/public/image-ads/jobs` — Queue an image ad job
- `POST /api/public/subtitle/jobs` — Render captions onto a video
- `GET /api/public/brands` — List saved brand workspaces
- `POST /api/public/brands` — Ingest a brand from a website URL

The full path list, request bodies, and response schemas live in OpenAPI: https://api.ezugc.ai/openapi.json

## Errors

Failures return `application/json` with `{ error, code, message, hint }`. `error` and `message` are the same human summary. `code` is stable. `hint` tells you how to fix the request.

```json
{
  "error": "A paid EzUGC subscription is required to use the public API.",
  "code": "PUBLIC_API_SUBSCRIPTION_REQUIRED",
  "message": "A paid EzUGC subscription is required to use the public API.",
  "hint": "Subscribe at https://www.ezugc.ai/pricing then create a key."
}
```

## MCP

Same paid key, from Claude Code, Cursor, or any MCP client: https://www.ezugc.ai/mcp

- Developer portal: https://www.ezugc.ai/developers
- Markdown twin: https://www.ezugc.ai/docs.md