Video
Generate AI videos from text prompts or images using cutting-edge video generation models
Generate AI videos from text prompts or images using cutting-edge video generation models.
Create Video
Generate AI videos from text prompts, optionally using an image as the starting frame.
POST /ugc/videoRequest Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer token with your API key |
Content-Type | Yes | application/json |
Request Body
Text-to-Video
{
"projectId": "clxxx...",
"prompt": "A cinematic slow-motion shot of coffee being poured into a cup",
"model": "sora-2-pro",
"duration": "10",
"aspectRatio": "landscape",
"tier": "pro",
"variants": 1
}Image-to-Video
{
"projectId": "clxxx...",
"prompt": "The product slowly rotates with dramatic lighting",
"model": "kling-2.6",
"duration": "5",
"aspectRatio": "9:16",
"imageUrl": "https://example.com/product.jpg",
"variants": 2
}Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
projectId | string | Yes | - | Your project ID (CUID format) |
prompt | string | Yes | - | Video description (10-3000 characters) |
model | string | Yes | - | Model: "sora-2-pro", "veo-3.1", or "kling-2.6" |
duration | string | Yes | - | Duration in seconds (varies by model) |
aspectRatio | string | No | - | Aspect ratio (varies by model) |
imageUrl | string | No | - | HTTPS URL to starting image for image-to-video |
tier | string | Conditional | - | Required for sora-2-pro: "standard" or "pro" |
variants | number | No | 1 | Number of video variants (1-8) |
Models
sora-2-pro
OpenAI's Sora model for high-quality video generation.
| Parameter | Options |
|---|---|
| Duration | "10", "15" |
| Aspect Ratio | "portrait", "landscape" |
| Tier | Required: "standard" or "pro" |
veo-3.1
Google's Veo model for fast, high-quality videos.
| Parameter | Options |
|---|---|
| Duration | "8" |
| Aspect Ratio | "16:9", "9:16" |
| Tier | Not applicable |
kling-2.6
Kuaishou's Kling model, excellent for image-to-video.
| Parameter | Options |
|---|---|
| Duration | "5", "10" |
| Aspect Ratio | "9:16", "16:9", "1:1" |
| Tier | Not applicable |
Image Requirements
When using imageUrl for image-to-video, the URL must be publicly accessible via HTTPS.
When using imageUrl for image-to-video:
- Formats: JPEG, PNG, WebP
- Max size: 10MB
- Protocol: Must be HTTPS (no HTTP, localhost, or private IPs)
- Accessibility: URL must be publicly accessible
Response
Success Response (202 Accepted)
{
"data": {
"jobs": [
{
"ugcId": "clxxx...",
"variantIndex": 0,
"status": "PENDING",
"creditsCharged": 150
}
],
"totalCreditsCharged": 150,
"remainingCredits": 4850
},
"meta": {
"requestId": "req_abc123def456",
"timestamp": "2025-01-15T10:30:00.000Z"
}
}Examples
# Text-to-Video with Sora
curl -X POST https://api.ugclab.app/api/v1/ugc/video \
-H "Authorization: Bearer ugc_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"projectId": "clxyz123...",
"prompt": "A drone shot flying over a beautiful coastal city at sunset",
"model": "sora-2-pro",
"duration": "15",
"aspectRatio": "landscape",
"tier": "pro",
"variants": 1
}'
# Image-to-Video with Kling
curl -X POST https://api.ugclab.app/api/v1/ugc/video \
-H "Authorization: Bearer ugc_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"projectId": "clxyz123...",
"prompt": "The product slowly rotates with particles floating around it",
"model": "kling-2.6",
"duration": "5",
"aspectRatio": "9:16",
"imageUrl": "https://example.com/my-product.jpg",
"variants": 2
}'const response = await fetch('https://api.ugclab.app/api/v1/ugc/video', {
method: 'POST',
headers: {
'Authorization': 'Bearer ugc_your_api_key',
'Content-Type': 'application/json',
},
body: JSON.stringify({
projectId: 'clxyz123...',
prompt: 'A cinematic product reveal with dramatic lighting',
model: 'veo-3.1',
duration: '8',
aspectRatio: '16:9',
variants: 1,
}),
});
const data = await response.json();
if (response.ok) {
console.log('Videos created:', data.data.jobs);
console.log('Credits charged:', data.data.totalCreditsCharged);
} else {
console.error('Error:', data.error.message);
}import requests
response = requests.post(
'https://api.ugclab.app/api/v1/ugc/video',
headers={
'Authorization': 'Bearer ugc_your_api_key',
'Content-Type': 'application/json',
},
json={
'projectId': 'clxyz123...',
'prompt': 'A cinematic product reveal with dramatic lighting',
'model': 'veo-3.1',
'duration': '8',
'aspectRatio': '16:9',
'variants': 1,
}
)
data = response.json()
if response.ok:
print(f"Videos created: {len(data['data']['jobs'])}")
print(f"Credits charged: {data['data']['totalCreditsCharged']}")
else:
print(f"Error: {data['error']['message']}")Error Codes
| Code | HTTP Status | Description |
|---|---|---|
VALIDATION_ERROR | 400 | Invalid request parameters |
IMAGE_DOWNLOAD_FAILED | 400 | Failed to download starting image |
INSUFFICIENT_CREDITS | 402 | Not enough credits in workspace |
PROJECT_NOT_FOUND | 404 | Project not found in workspace |
IP_RATE_LIMITED | 429 | Too many authentication attempts |
RATE_LIMIT_EXCEEDED | 429 | API rate limit exceeded |
INTERNAL_ERROR | 500 | Internal server error |
Best Practices
-
Match model to use case:
sora-2-pro: Best for cinematic, high-quality productionsveo-3.1: Fast turnaround, good qualitykling-2.6: Excellent for image-to-video, product animations
-
Image-to-video tips:
- Use high-quality starting images
- Match aspect ratio to your image dimensions
- Be descriptive about the motion you want
-
Prompt writing:
- Be specific about camera movements, lighting, and mood
- Include temporal descriptions (slow-motion, timelapse, etc.)
- Mention style references (cinematic, documentary, etc.)
-
Use webhooks: Configure webhooks for real-time status updates instead of polling.
-
Test efficiently: Start with shorter durations and fewer variants when testing.
Related
- Image API - Generate images that can be used as starting frames
- Projects API - Get project IDs
- Job Status API - Check job progress
- Authentication - API key setup