API Reference

The U-Gen REST API lets you programmatically create AI-powered UGC videos, manage personas, voices, and templates. All endpoints use the base URL below.

Base URL

https://api.u-gen.ai/api/v1

Authentication

U-Gen supports two authentication methods. Use API keys for server-to-server integration, or JWT tokens for user-session requests from the frontend. JWT takes priority if both are provided.

API Key

X-API-Key: YOUR_KEY

Server-to-server, B2B integration

JWT

Authorization: Bearer TOKEN

Frontend sessions, user actions

Authentication

curl -X GET https://api.u-gen.ai/api/v1/jobs \
  -H "X-API-Key: YOUR_API_KEY"

API Key Management

Generate API keys from your API Keys page. Keys are scoped to your account and share your prepaid credit balance.

Pagination

List endpoints use offset-based pagination with page and page_size query parameters. Default page size is 20, maximum is 100.

GET /api/v1/jobs?page=1&page_size=20

{
  "items": [...],
  "total": 42,
  "page": 1,
  "page_size": 20,
  "total_pages": 3
}

Error Handling

The API uses two error response formats depending on the error type:

Application Errors (401, 402, 403, 404, 409, 429, 5xx)

Business logic and auth errors return a nested error object with a machine-readable code, human-readable message, and optional details.

Application Error

// Application errors (401, 402, 403, 404, 409, 429, 5xx)
{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits",
    "details": {
      "required": 86,
      "available": 12
    }
  }
}

Validation Errors (422)

Missing or invalid request fields return a detail array with per-field error information including the field location and a human-readable message.

Validation Error (422)

// Validation errors (422 — missing or invalid fields)
{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "product_image_url"],
      "msg": "Field required",
      "input": { "product_name": "test" }
    }
  ]
}

Status	Meaning	Common Cause
400	Bad Request	Invalid parameters, missing required fields, or invalid state transition.
401	Unauthorized	Missing or invalid API key / JWT token.
402	Payment Required	Insufficient credits for the requested operation.
403	Forbidden	Access denied — wrong tenant or insufficient permissions.
404	Not Found	Resource does not exist or belongs to another tenant.
409	Conflict	Duplicate resource or idempotency key mismatch.
429	Too Many Requests	Job creation limit exceeded. Includes Retry-After header.
500	Internal Error	Server error — retry with exponential backoff.
502	Bad Gateway	External service (KIE, ElevenLabs, etc.) returned an error.
503	Service Unavailable	Circuit breaker open — external service temporarily unavailable.
504	Gateway Timeout	External service timed out (video generation, voice synthesis).

Idempotency

The job creation endpoint supports idempotency via the idempotency_key field in the request body. If omitted, a unique key is auto-generated. Sending the same key returns the original response without creating a duplicate job.

Job Limits

Your account has limits on concurrent and daily job creation. Exceeding these limits returns a 429 response with a Retry-After header. These limits apply to job creation only — read endpoints (GET) are not rate-limited.