Render
POST /v1/render
Submit a timeline for video rendering. This is the primary endpoint for composing and rendering videos.
Request
| Field | Type | Required | Description |
|---|---|---|---|
timeline | object | Yes | Timeline with tracks and clips |
output | object | Yes | Output format, resolution, and options |
callback | string | No | Webhook URL for completion notification |
metadata | object | No | Custom key-value metadata attached to the job |
Full Multi-Track Example
This example creates a 15-second video with:
- Track 0 (foreground): Title text with fade transition
- Track 1 (middle): Logo overlay in the corner
- Track 2 (background): Two image clips with slide transitions
curl
curl -X POST https://api.vidiking.com/v1/render \
-H "Authorization: Bearer $VIDIKING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"timeline": {
"background": "#1a1a2e",
"soundtrack": {
"src": "https://example.com/bgm.mp3",
"effect": "fadeInFadeOut",
"volume": 0.3
},
"tracks": [
{
"clips": [
{
"asset": {
"type": "title",
"text": "Product Launch 2025",
"style": "future",
"size": "large",
"color": "#ffffff"
},
"start": 1,
"length": 5,
"transition": {
"in": "fade",
"out": "fade"
}
},
{
"asset": {
"type": "title",
"text": "Available Now",
"style": "minimal",
"size": "medium",
"color": "#00d4ff"
},
"start": 8,
"length": 5,
"transition": {
"in": "slideUp",
"out": "fade"
}
}
]
},
{
"clips": [
{
"asset": {
"type": "image",
"src": "https://example.com/logo.png"
},
"start": 0,
"length": 15,
"scale": 0.15,
"offset": { "x": 0.4, "y": -0.4 },
"opacity": 0.8
}
]
},
{
"clips": [
{
"asset": {
"type": "image",
"src": "https://example.com/hero-1.jpg"
},
"start": 0,
"length": 7.5,
"fit": "cover",
"transition": {
"in": "fade",
"out": "slideLeft"
},
"effect": "zoomIn"
},
{
"asset": {
"type": "image",
"src": "https://example.com/hero-2.jpg"
},
"start": 7.5,
"length": 7.5,
"fit": "cover",
"transition": {
"in": "slideRight",
"out": "fade"
},
"effect": "zoomOut"
}
]
}
]
},
"output": {
"format": "mp4",
"resolution": "1080",
"fps": 30,
"quality": "high",
"aspectRatio": "16:9"
},
"callback": "https://your-server.com/webhooks/vidiking"
}'
Node.js
import Vidiai from '@vidiking/sdk';
const client = new Vidiai({ apiKey: process.env.VIDIKING_API_KEY });
const { jobId } = await client.render({
timeline: {
background: '#1a1a2e',
soundtrack: {
src: 'https://example.com/bgm.mp3',
effect: 'fadeInFadeOut',
volume: 0.3,
},
tracks: [
{
clips: [
{
asset: { type: 'title', text: 'Product Launch 2025', style: 'future', size: 'large' },
start: 1,
length: 5,
transition: { in: 'fade', out: 'fade' },
},
{
asset: { type: 'title', text: 'Available Now', style: 'minimal', size: 'medium', color: '#00d4ff' },
start: 8,
length: 5,
transition: { in: 'slideUp', out: 'fade' },
},
],
},
{
clips: [
{
asset: { type: 'image', src: 'https://example.com/logo.png' },
start: 0,
length: 15,
scale: 0.15,
offset: { x: 0.4, y: -0.4 },
opacity: 0.8,
},
],
},
{
clips: [
{
asset: { type: 'image', src: 'https://example.com/hero-1.jpg' },
start: 0,
length: 7.5,
fit: 'cover',
transition: { in: 'fade', out: 'slideLeft' },
effect: 'zoomIn',
},
{
asset: { type: 'image', src: 'https://example.com/hero-2.jpg' },
start: 7.5,
length: 7.5,
fit: 'cover',
transition: { in: 'slideRight', out: 'fade' },
effect: 'zoomOut',
},
],
},
],
},
output: { format: 'mp4', resolution: '1080', fps: 30, quality: 'high' },
callback: 'https://your-server.com/webhooks/vidiking',
});
console.log('Job submitted:', jobId);
Python
from vidiai import Vidiai
client = Vidiking(api_key="your_api_key")
result = client.render({
"timeline": {
"background": "#1a1a2e",
"soundtrack": {
"src": "https://example.com/bgm.mp3",
"effect": "fadeInFadeOut",
"volume": 0.3,
},
"tracks": [
{
"clips": [
{
"asset": {"type": "title", "text": "Product Launch 2025", "style": "future", "size": "large"},
"start": 1,
"length": 5,
"transition": {"in": "fade", "out": "fade"},
},
{
"asset": {"type": "title", "text": "Available Now", "style": "minimal", "size": "medium"},
"start": 8,
"length": 5,
"transition": {"in": "slideUp", "out": "fade"},
},
]
},
{
"clips": [
{
"asset": {"type": "image", "src": "https://example.com/logo.png"},
"start": 0,
"length": 15,
"scale": 0.15,
"offset": {"x": 0.4, "y": -0.4},
"opacity": 0.8,
}
]
},
{
"clips": [
{
"asset": {"type": "image", "src": "https://example.com/hero-1.jpg"},
"start": 0,
"length": 7.5,
"fit": "cover",
"transition": {"in": "fade", "out": "slideLeft"},
},
{
"asset": {"type": "image", "src": "https://example.com/hero-2.jpg"},
"start": 7.5,
"length": 7.5,
"fit": "cover",
"transition": {"in": "slideRight", "out": "fade"},
},
]
},
],
},
"output": {"format": "mp4", "resolution": "1080", "fps": 30, "quality": "high"},
"callback": "https://your-server.com/webhooks/vidiking",
})
print("Job submitted:", result.job_id)
Response
{
"id": "job_abc123",
"status": "QUEUED",
"created_at": "2025-01-15T10:30:00Z"
}
Get Render Status
GET /v1/render/{id}
curl https://api.vidiking.com/v1/render/job_abc123 \
-H "Authorization: Bearer $VIDIKING_API_KEY"
See Jobs & Rendering for full lifecycle details.
Output Options
| Parameter | Type | Values | Default |
|---|---|---|---|
format | string | mp4, gif, webm, mov | mp4 |
resolution | string | preview, sd, hd, 1080, 4k | hd |
fps | number | 15, 24, 25, 30, 60 | 25 |
quality | string | low, medium, high | medium |
aspectRatio | string | 16:9, 9:16, 1:1, 4:5 | 16:9 |
Effects
Apply motion effects to clips:
| Effect | Description |
|---|---|
zoomIn | Slow zoom in |
zoomOut | Slow zoom out |
slideLeft | Slow pan left |
slideRight | Slow pan right |
slideUp | Slow pan up |
slideDown | Slow pan down |
Error Codes
| Code | HTTP Status | Description |
|---|---|---|
INVALID_TIMELINE | 400 | Timeline JSON is malformed |
INVALID_OUTPUT | 400 | Invalid output configuration |
INSUFFICIENT_CREDITS | 402 | Not enough balance |
RATE_LIMITED | 429 | Too many requests |