JSON in, video out with docs, webhooks and pricing

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"
  }
}

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 video pack checkout endpoints.

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_seconds": 8,
    "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"
}