JSON to Video Generator and API: JSON in, video out

Complete API map

This page documents the public JSON-to-video surface and links to the adjacent API docs that share the same SamAutomation API key. Use this map to decide which endpoint group you need before you build an n8n workflow or custom integration.

Payload contract (core endpoints)

Core endpoints accept either a root payload or a nested data object.

{
  "media_list": [...],
  "settings": {...}
}

{
  "data": {
    "media_list": [...],
    "settings": {...}
  }
}

Request schemas by endpoint

Use this as the exact minimum/optional field reference for core JSON-to-video endpoints.

Export destinations per job

Add optional exports settings to deliver completed videos directly to your workflow tools. This supports callback webhooks, FTP/SFTP upload, and email notifications from the same render request.

{
  "data": {
    "media_list": [{"type": "image", "url": "https://cdn.example.com/frame.jpg", "duration": 3}],
    "settings": {"aspect_ratio": "16:9"},
    "exports": {
      "callback_url": "https://hooks.example.com/video-completed",
      "callback_secret": "your-shared-secret",
      "destinations": [
        {"type": "email", "to": ["ops@example.com", "creator@example.com"]},
        {
          "type": "sftp",
          "host": "files.example.com",
          "port": 22,
          "username": "deploy",
          "password": "YOUR_PASSWORD",
          "path": "/incoming/videos/"
        }
      ]
    }
  }
}

Mix video endpoint

POST /api/function/video-generation/mix-video

• Requires media_list.
• Optional: voice_url, background_url, transcripts, settings, exports.
• Rate limit: 5/m per authenticated API user.

{
  "data": {
    "media_list": [
      {"type": "image", "url": "https://cdn.example.com/scene-1.jpg", "duration": 3},
      {"type": "video", "url": "https://cdn.example.com/scene-2.mp4"}
    ],
    "voice_url": "https://cdn.example.com/voice.mp3",
    "background_url": "https://cdn.example.com/music.mp3",
    "transcripts": [
      {"words": "Welcome to SamAutomation", "start": 0.0, "end": 2.0}
    ],
    "settings": {
      "aspect_ratio": "16:9",
      "transition_type": "fade"
    }
  }
}

{
  "success": true,
  "message": "Video generation started",
  "data": {
    "id": "3ec95f88-54bc-4b91-b2d0-d02da8929b4a",
    "progress_url": "/api/function/video-generation/progress/3ec95f88-54bc-4b91-b2d0-d02da8929b4a",
    "celery_task_id": "26767b7f-b642-44ef-8f16-0d99069ed844"
  }
}

{
  "success": true,
  "message": "Video generation started",
  "data": {
    "id": "f6159e7c-9a84-4c58-b9ad-1dd3a3ea12b1",
    "progress_url": "/api/function/video-generation/progress/f6159e7c-9a84-4c58-b9ad-1dd3a3ea12b1",
    "celery_task_id": "5dd8d7b5-a050-41ef-a11d-ecf1c4ef1495"
  }
}

Transcript object contract (Mix video)

When you send transcripts, each entry should contain timed words.

// valid
{
  "transcripts": [
    {"words": "First caption", "start": 0.0, "end": 1.8},
    {"words": "Second caption", "start": 1.9, "end": 3.4}
  ]
}

// avoid this shape
{
  "transcripts": [
    {"text": "First caption", "start": 0.0, "end": 1.8}
  ]
}

Simple video endpoint

POST /api/function/video-generation/simple-video

• Requires media_list.
• Each media item must include type and url.
• Allowed media types: video and image.
• Applies strict settings validation (see validation matrix above).
• Rate limit: 5/m.

{
  "media_list": [
    {"type": "image", "url": "https://cdn.example.com/slide.jpg", "duration": 4}
  ],
  "settings": {
    "aspect_ratio": "9:16",
    "fps": 30,
    "output_quality": "high",
    "loop_audio": false,
    "transition_type": "fade",
    "transition_duration": 0.5
  }
}

Loop video endpoint

POST /api/function/video-generation/loop-video

• Top-level type must be exactly LoopVideo.
• data.media_list is required.
• data.background_url is required.
• data.duration is optional but, if sent, must be a positive number.
• Rate limit: 5/m.

{
  "type": "LoopVideo",
  "data": {
    "media_list": [
      {"type": "video", "url": "https://cdn.example.com/loop-source.mp4"}
    ],
    "background_url": "https://cdn.example.com/bg-music.mp3",
    "duration": 12,
    "settings": {
      "aspect_ratio": "16:9",
      "loop_video": true
    }
  }
}

{
  "success": true,
  "message": "Video generation started",
  "data": {
    "id": "09574c7d-9441-4eca-a8ee-e0d11f3f1ca9",
    "celery_task_id": "5f79f7f5-84ec-46a4-a844-d9668d7af385"
  }
}

Reference clients (Python + JavaScript)

These examples show submit + poll flow for core JSON-to-video endpoints.

import time
import requests

BASE = "https://samautomation.work"
HEADERS = {"X-API-Key": "YOUR_KEY", "Content-Type": "application/json"}

payload = {
    "data": {
        "media_list": [{"type": "image", "url": "https://cdn.example.com/a.jpg", "duration": 3}],
        "settings": {"aspect_ratio": "9:16"}
    }
}

# mix-video (replace path for simple-video or loop-video)
r = requests.post(f"{BASE}/api/function/video-generation/mix-video", headers=HEADERS, json=payload, timeout=60)
job = r.json()["data"]["id"]

while True:
    s = requests.get(f"{BASE}/api/function/video-generation/progress/{job}", headers=HEADERS, timeout=30).json()["data"]
    if s["status"] in {"completed", "failed", "cancelled", "timeout"}:
        print(s)
        break
    time.sleep(5)

const BASE = "https://samautomation.work";
const headers = {
  "X-API-Key": "YOUR_KEY",
  "Content-Type": "application/json",
};

const create = await fetch(`${BASE}/api/function/video-generation/simple-video`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    media_list: [{ type: "image", url: "https://cdn.example.com/a.jpg", duration: 3 }],
    settings: { aspect_ratio: "16:9" },
  }),
});

const { data } = await create.json();
let done = false;
while (!done) {
  const statusRes = await fetch(`${BASE}/api/function/video-generation/progress/${data.id}`, { headers });
  const statusPayload = await statusRes.json();
  const status = statusPayload.data.status;
  done = ["completed", "failed", "cancelled", "timeout"].includes(status);
  if (!done) await new Promise((r) => setTimeout(r, 5000));
}

For loop generation, call /api/function/video-generation/loop-video and include top-level type: "LoopVideo".

Task tracking and usage endpoints

{
  "success": true,
  "data": {
    "id": "3ec95f88-54bc-4b91-b2d0-d02da8929b4a",
    "status": "processing",
    "progress": 0.6,
    "created_at": "2026-02-28T14:10:00+00:00",
    "completed_at": null,
    "output_url": null,
    "error": null,
    "settings": {
      "aspect_ratio": "9:16",
      "duration": 0,
      "size_bytes": 0
    }
  }
}

{
  "success": true,
  "data": {
    "window_days": 30,
    "since": "2026-01-29T12:00:00+00:00",
    "totals": {
      "tasks": 42,
      "completed": 38,
      "failed": 2,
      "cancelled": 1,
      "timeout": 1,
      "success_rate": 0.9048
    },
    "by_status": {
      "pending": 0,
      "processing": 0,
      "completed": 38,
      "failed": 2,
      "cancelled": 1,
      "timeout": 1
    },
    "api_key": {
      "name": "Production",
      "masked_key": "abcd...wxyz",
      "usage_count": 128,
      "last_used": "2026-02-28T13:59:00+00:00"
    }
  }
}

Advanced renderer API

POST /api/render/advanced-video and GET /api/render/advanced-video/progress/{task_id}

• Rate limit: 3/m for create requests.
• Request body can be at root or in config.
• Supports render_options.mode: preview (sync) or full (async).
• Optional template_id merges saved template settings before validation.

{
  "config": {
    "output_settings": {
      "aspect_ratio": "16:9",
      "resolution": "1080p",
      "framerate": 30
    },
    "media_inputs": {
      "main_clips": [
        {"type": "video", "url": "https://cdn.example.com/clip-a.mp4"},
        {"type": "image", "url": "https://cdn.example.com/clip-b.jpg", "duration": 3}
      ],
      "background": {"type": "color", "value": "#000000"}
    },
    "caption_elements": [
      {
        "text_content": "Launch day",
        "start_time": 0,
        "duration": 2,
        "styling": {"font_size": 42, "text_color": "#FFFFFF"}
      }
    ],
    "audio_settings": {
      "background_music_url": "https://cdn.example.com/bg.mp3",
      "background_music_volume_percent": 20,
      "voice_over_url": "https://cdn.example.com/voice.mp3",
      "voice_over_volume_percent": 100
    },
    "render_options": {
      "mode": "full",
      "quality": "high"
    }
  }
}

// preview mode
{
  "success": true,
  "message": "Preview generated successfully",
  "data": {
    "mode": "preview",
    "preview_url": "https://media.samautomation.work/previews/preview_a1b2c3.mp4",
    "request_id": "a1b2c3d4"
  }
}

// full mode
{
  "success": true,
  "message": "Advanced video generation started",
  "data": {
    "id": "c5b58dc9-4c17-4380-bf34-b3ec3c10f06f",
    "mode": "full",
    "progress_url": "/api/render/advanced-video/progress/c5b58dc9-4c17-4380-bf34-b3ec3c10f06f",
    "estimated_time": "2-5 minutes",
    "request_id": "f8e96a10",
    "celery_task_id": "a2be3da1-4f3a-4f5e-b7ce-7d7f71b0f5bb"
  }
}

Render-to-AutoCaptions flow

Use AutoCaptions when your JSON-to-video output needs burned-in social captions. In n8n, the normal flow is render first, poll until completed, then pass the completed output_url into the AutoCaptions API.

curl -X POST "https://samautomation.work/api/autocaptions/generate" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://media.samautomation.work/videos/final.mp4",
    "caption_type": "premium",
    "settings": {
      "font_family": "Montserrat",
      "font_size": 32,
      "vertical_position": "bottom75",
      "horizontal_alignment": "center",
      "text_color": "white",
      "stroke_color": "black",
      "stroke_width": 2,
      "refresh_interval": 1.5
    }
  }'

curl -X GET "https://samautomation.work/api/autocaptions/status/TASK_ID" \
  -H "X-API-Key: YOUR_KEY"

Full caption settings, responses, and billing routes are documented in the AutoCaptions API docs.

Async control endpoints

curl -X POST "https://samautomation.work/api/async/cancel/CELERY_TASK_ID" \
  -H "X-API-Key: YOUR_KEY"

Templates API (reusable render presets)

{
  "name": "My 9:16 Promo",
  "description": "Short promo style with captions",
  "category": "marketing",
  "is_public": false,
  "settings": {
    "output_settings": {"aspect_ratio": "9:16", "framerate": 30},
    "render_options": {"quality": "high"}
  }
}

Video billing and credit pack endpoints

For core JSON-to-video volume beyond plan limits, use the dashboard/session checkout flow for video credit packs.

Use /api/function/video-generation/usage-summary to monitor usage windows and avoid hard stops.

AI video API

Use the same SamAutomation key to generate AI videos via job endpoints. The available model list, constraints, options, and credit behavior are live.

{
  "model_id": "kling-3-0",
  "prompt": "Cinematic tracking shot in a rainy neon city",
  "image_urls": ["https://cdn.example.com/source.jpg"],
  "options": {
    "duration_s": 10,
    "aspect_ratio": "16:9",
    "quality_mode": "pro",
    "sound": true,
    "multiShots": true
  }
}

// create (HTTP 202)
{
  "success": true,
  "job_id": 148,
  "status": "running",
  "credits_charged": 220,
  "credits_remaining": 5230
}

// status
{
  "success": true,
  "job_id": 148,
  "status": "success",
  "result_urls": ["https://media.samautomation.work/ai/output-148.mp4"],
  "error_code": null,
  "error_message": null,
  "credits_charged": 220,
  "created_at": "2026-02-28T14:40:00+00:00",
  "completed_at": "2026-02-28T14:41:33+00:00"
}

Legacy AI route compatibility

New integrations should use POST /api/ai/jobs. The model-specific routes below remain available for existing clients and dashboards, but they are compatibility routes rather than the recommended path for new n8n workflows.

For full AI billing, topup, and legacy examples, open the dedicated AI API docs.

Developer tooling and n8n readiness

The REST endpoints are the stable source of truth today. For n8n users and AI agents, the fastest onboarding path is to combine the examples on this page with reusable workflows, a validation step, and machine-readable API metadata.