UGCLabUGCLab

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/video

Request Headers

HeaderRequiredDescription
AuthorizationYesBearer token with your API key
Content-TypeYesapplication/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

ParameterTypeRequiredDefaultDescription
projectIdstringYes-Your project ID (CUID format)
promptstringYes-Video description (10-3000 characters)
modelstringYes-Model: "sora-2-pro", "veo-3.1", or "kling-2.6"
durationstringYes-Duration in seconds (varies by model)
aspectRatiostringNo-Aspect ratio (varies by model)
imageUrlstringNo-HTTPS URL to starting image for image-to-video
tierstringConditional-Required for sora-2-pro: "standard" or "pro"
variantsnumberNo1Number of video variants (1-8)

Models

sora-2-pro

OpenAI's Sora model for high-quality video generation.

ParameterOptions
Duration"10", "15"
Aspect Ratio"portrait", "landscape"
TierRequired: "standard" or "pro"

veo-3.1

Google's Veo model for fast, high-quality videos.

ParameterOptions
Duration"8"
Aspect Ratio"16:9", "9:16"
TierNot applicable

kling-2.6

Kuaishou's Kling model, excellent for image-to-video.

ParameterOptions
Duration"5", "10"
Aspect Ratio"9:16", "16:9", "1:1"
TierNot 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

CodeHTTP StatusDescription
VALIDATION_ERROR400Invalid request parameters
IMAGE_DOWNLOAD_FAILED400Failed to download starting image
INSUFFICIENT_CREDITS402Not enough credits in workspace
PROJECT_NOT_FOUND404Project not found in workspace
IP_RATE_LIMITED429Too many authentication attempts
RATE_LIMIT_EXCEEDED429API rate limit exceeded
INTERNAL_ERROR500Internal server error

Best Practices

  1. Match model to use case:

    • sora-2-pro: Best for cinematic, high-quality productions
    • veo-3.1: Fast turnaround, good quality
    • kling-2.6: Excellent for image-to-video, product animations
  2. Image-to-video tips:

    • Use high-quality starting images
    • Match aspect ratio to your image dimensions
    • Be descriptive about the motion you want
  3. Prompt writing:

    • Be specific about camera movements, lighting, and mood
    • Include temporal descriptions (slow-motion, timelapse, etc.)
    • Mention style references (cinematic, documentary, etc.)
  4. Use webhooks: Configure webhooks for real-time status updates instead of polling.

  5. Test efficiently: Start with shorter durations and fewer variants when testing.

On this page