---
title: "EzUGC API Documentation"
description: "EzUGC public API docs: auth, endpoints, JSON errors, example curls, and the OpenAPI spec."
canonical: "https://www.ezugc.ai/docs.md"
last-updated: "2026-08-26"
---
# 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

Canonical versioned prefix: `https://api.ezugc.ai/api/public/v1` (for example `GET /api/public/v1/me`). Unversioned `/api/public` is the same v1 contract. Breaking changes will ship as `/v2`; there is no `/v2` today.

## 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
- AGENTS.md: https://www.ezugc.ai/AGENTS.md
- Markdown twin: https://www.ezugc.ai/docs.md