API Documentation
Complete reference for the Ultimate Creator AI API
Overview
The Ultimate Creator AI API provides an asynchronous pipeline for AI-powered video generation. Submit a prompt with your desired parameters, and our system will process the request in the background. Once complete, you'll receive a webhook notification with a time-limited download URL for your generated video.
Important: AI video generation takes 2–8 minutes depending on length and complexity. Do not hold HTTP connections open. Use webhooks to receive completion notifications.
Base URL
https://api.ultimatecreator.aiAuthentication
All API requests require a Bearer token in the Authorization header. You can create and manage API keys from the API Keys page. Keys are prefixed with ucai_live_ for production and ucai_test_ for sandbox environments.
Authorization: Bearer ucai_live_abc123def456...Quick Start
Generate your first video with a single API call. The response includes a job_id you can use to poll status, and a webhook will fire when the video is ready.
curl -X POST https://api.ultimatecreator.ai/v1/videos/generate \
-H "Authorization: Bearer ucai_live_abc123" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: req_unique_001" \
-d '{
"prompt": "A cyberpunk cityscape at sunset with neon lights",
"webhook_url": "https://your-app.com/webhooks/video",
"target_length_seconds": 30,
"resolution": "1080p",
"style": "cinematic"
}'Endpoint Reference
All endpoints are versioned under /v1. Click a group to expand its endpoints.
Webhook Verification
Every webhook request includes an Ultimate-Signature header containing an HMAC-SHA256 hex digest of the request body, signed with your webhook secret. Always verify this signature before processing the payload to prevent spoofed events.
Signature Verification
import crypto from "crypto";
function verifyWebhookSignature(
payload: string,
signature: string,
secret: string
): boolean {
const expected = crypto
.createHmac("sha256", secret)
.update(payload)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
// In your webhook handler:
app.post("/webhooks/video", (req, res) => {
const signature = req.headers["ultimate-signature"] as string;
const isValid = verifyWebhookSignature(
JSON.stringify(req.body),
signature,
process.env.WEBHOOK_SECRET!
);
if (!isValid) {
return res.status(401).json({ error: "Invalid signature" });
}
// Process the webhook event
const { job_id, status, download_url } = req.body;
console.log(`Job ${job_id}: ${status}`);
res.status(200).json({ received: true });
});Webhook Payload Examples
{
"event": "video.completed",
"job_id": "job_abc123def456",
"status": "completed",
"created_at": "2026-03-06T08:30:00Z",
"completed_at": "2026-03-06T08:34:22Z",
"download_url": "https://cdn.ultimatecreator.ai/v/abc123.mp4",
"download_expires_at": "2026-03-07T08:34:22Z",
"metadata": {
"duration_seconds": 30,
"resolution": "1920x1080",
"file_size_bytes": 48234567,
"credits_used": 150
}
}Error Codes
The API returns structured JSON error responses. Each error includes a machine-readable code field and a human-readable message.
| Code | Error | Description | Action |
|---|---|---|---|
| 400 | CONTENT_MODERATED | Prompt was flagged by content moderation filters | Revise the prompt and resubmit |
| 400 | VALIDATION_ERROR | Request body failed schema validation | Check the error details for invalid fields |
| 401 | UNAUTHORIZED | Missing or invalid API key | Verify your Authorization header |
| 402 | INSUFFICIENT_CREDITS | Not enough credits to process the request | Purchase additional credits or upgrade plan |
| 403 | FORBIDDEN | API key does not have permission for this resource | Check key permissions in the dashboard |
| 403 | IP_MISMATCH | Request IP is not in the API key allowlist | Update the IP allowlist in API key settings |
| 404 | NOT_FOUND | The requested resource does not exist | Verify the resource ID and endpoint path |
| 429 | RATE_LIMITED | Too many requests — exceeded 60 req/min limit | Wait and retry with exponential backoff |
| 503 | QUEUE_FAILED | Failed to enqueue job due to temporary overload | Retry with an idempotency key after a few seconds |
Prompt was flagged by content moderation filters
Revise the prompt and resubmit
Request body failed schema validation
Check the error details for invalid fields
Missing or invalid API key
Verify your Authorization header
Not enough credits to process the request
Purchase additional credits or upgrade plan
API key does not have permission for this resource
Check key permissions in the dashboard
Request IP is not in the API key allowlist
Update the IP allowlist in API key settings
The requested resource does not exist
Verify the resource ID and endpoint path
Too many requests — exceeded 60 req/min limit
Wait and retry with exponential backoff
Failed to enqueue job due to temporary overload
Retry with an idempotency key after a few seconds
Rate Limiting
API requests are rate-limited to 60 requests per minute per IP address. When you exceed the limit, you'll receive a 429 response. Use exponential backoff for retries.
| Header | Description |
|---|---|
| X-RateLimit-Limit | Maximum number of requests allowed per window (60) |
| X-RateLimit-Remaining | Number of requests remaining in the current window |
| X-RateLimit-Reset | Unix timestamp (seconds) when the current rate-limit window resets |
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1709722800
Retry-After: 42
{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Retry after 42 seconds."
}
}Idempotency
To safely retry requests without creating duplicate jobs, include an Idempotency-Key header with a unique string (e.g., a UUID). If the server has already processed a request with the same key, it will return the original response instead of creating a new resource. Keys expire after 24 hours.
POST /v1/videos/generate HTTP/1.1
Host: api.ultimatecreator.ai
Authorization: Bearer ucai_live_abc123
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
{
"prompt": "A serene mountain landscape at dawn",
"webhook_url": "https://your-app.com/webhooks/video",
"target_length_seconds": 15
}Best practice: Always include an idempotency key for POST requests, especially for video generation. This protects against network retries and double-charging credits.