ViddyFlow Documentation

Getting Started

ViddyFlow is an AI-powered highlight studio that automatically transforms your livestream VODs into engaging highlight videos and social-ready clips.

1. Create Your Account

Sign up at app.viddyflow.com/register and get 300 free credits to start.

2. Submit Your VOD URL

Paste the URL to your Twitch VOD. Direct file uploads coming soon.

3. Choose Processing Mode

Select from 6 processing tiers ranging from Rapid Sprint (18 credits/hour) to Director Finish (90 credits/hour).

4. Get Your Highlights

Receive AI-generated highlight videos and vertical shorts optimized for social platforms.

API Documentation

ViddyFlow provides a RESTful API for programmatic access to all features. Base URL: https://api.viddyflow.com

Authentication

Generate your API key in the API Access dashboard and include it in the request header:

X-API-Key: your_api_key_here

Quick Start

Follow this checklist to mirror the dashboard experience via API. The request schema matches the "New Job" form and the service measures the VOD duration automatically as soon as a job is queued.

  1. Generate a key and store it securely—each value is displayed once.
  2. Add the key to every call with the X-API-Key header.
  3. POST to /jobs with your VOD URL and desired settings. Duration is calculated automatically.
  4. The response is a lightweight acknowledgement that echoes the job id and credit charge. Use that id to poll /jobs/:id.
  5. Provide run presets, highlight bounds, streamer metadata, and optional webhook URLs to align with your dashboard defaults.
  6. Check status via GET /jobs/:id or rely on your webhook for completion events.

Request Fields

streamer_name, streamer_pronouns, game_name

Improve metadata on the final cut.

streamer_twitch_url / streamer_twitter_url

Optional social links for title/description generation.

run_profiles

Choose any combination of balanced, audience, or streamer presets.

run_overrides

Override the weights, clip cohesion, and target length per preset (see examples below).

parameters

Supply min_highlight_duration / max_highlight_duration just like the dashboard sliders.

webhook_url

Subscribe to job status callbacks.

Tip: Duration fields are automatically calculated based on your VOD. Just provide the URL and your preferred settings!

Create Processing Job

POST /api/jobs

Submit a VOD for AI processing to generate highlights and clips.

Full Request Example:

{
  "vod_url": "https://twitch.tv/videos/123456789",
  "streamer_name": "StreamerName",
  "game_name": "Game Name",
  "streamer_pronouns": "they/them",
  "streamer_twitch_url": "https://twitch.tv/StreamerName",
  "webhook_url": "https://hooks.example.com/viddyflow/status",
  "run_profiles": ["audience"],
  "model_preset": "rapid_sprint",
  "parameters": {
    "min_highlight_duration": 30,
    "max_highlight_duration": 60
  }
}

Model Presets:

  • • rapid_sprint - 18 credits/hour (fastest)
  • • stable_tempo - 25 credits/hour
  • • creator_focus - 38 credits/hour (recommended)
  • • studio_polish - 55 credits/hour
  • • auto_balance - 65 credits/hour
  • • director_finish - 90 credits/hour (maximum quality)

Run Profiles:

balanced - Blend hype with creator moments
  • • audience_weight: 0.5, streamer_weight: 0.5
  • • similarity_threshold: 0.7 (clip cohesion)
  • • target_duration_minutes: 8
audience - Chat spikes & viral reactions
  • • audience_weight: 0.8, streamer_weight: 0.2
  • • similarity_threshold: 0.7
  • • target_duration_minutes: 5
streamer - Playmaking & commentary
  • • audience_weight: 0.2, streamer_weight: 0.8
  • • similarity_threshold: 0.7
  • • target_duration_minutes: 10

Python Example:

import requests

API_BASE = "https://api.viddyflow.com"
API_KEY = "your_api_key_here"

payload = {
    "vod_url": "https://twitch.tv/videos/123456789",
    "streamer_name": "StreamerName",
    "game_name": "Game Name",
    "run_profiles": ["audience"],
    "model_preset": "rapid_sprint",
    "parameters": {
        "min_highlight_duration": 30,
        "max_highlight_duration": 60
    }
}

response = requests.post(
    f"{API_BASE}/jobs",
    headers={"X-API-Key": API_KEY},
    json=payload,
    timeout=30,
)
response.raise_for_status()
data = response.json()
print(f"Job ID: {data['id']}")
print(f"Credit cost: {data['credit_cost']}")

Node.js Example:

const API_BASE = "https://api.viddyflow.com";
const API_KEY = "your_api_key_here";

async function submitJob() {
  const payload = {
    vod_url: "https://twitch.tv/videos/123456789",
    streamer_name: "StreamerName",
    game_name: "Game Name",
    run_profiles: ["audience"],
    model_preset: "rapid_sprint",
    parameters: {
      min_highlight_duration: 30,
      max_highlight_duration: 60
    }
  };

  const response = await fetch(`${API_BASE}/jobs`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": API_KEY,
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    throw new Error(`Failed: ${response.status}`);
  }

  const data = await response.json();
  console.log("Job ID:", data.id);
  console.log("Credit cost:", data.credit_cost);
}

submitJob().catch(console.error);

Response:

{
  "id": "abc123-def456-ghi789",
  "status": "pending",
  "webhook_url": null,
  "created_at": "2025-12-01T11:01:09.745640Z",
  "updated_at": "2025-12-01T11:01:10.986966Z",
  "credit_cost": 374,
  "message": "Job accepted. Poll /jobs/abc123-def456-ghi789 or await your webhook callback for results.",
  "artifact_url": null
}

Get Job Status

GET /api/jobs/:job_id

Check the status and progress of a processing job.

Python Example:

job_id = data["id"]
status_resp = requests.get(
    f"{API_BASE}/jobs/{job_id}",
    headers={"X-API-Key": API_KEY},
    timeout=30,
)
print("Status:", status_resp.json())

Node.js Example:

if (data.id) {
  const statusResponse = await fetch(`${API_BASE}/jobs/${data.id}`, {
    headers: { "X-API-Key": API_KEY },
  });
  console.log("Status:", await statusResponse.json());
}

Response (pending):

{
  "id": "abc123-def456-ghi789",
  "status": "pending",
  "step": "Waiting for worker",
  "webhook_url": null,
  "created_at": "2025-12-01T11:01:09.745640Z",
  "updated_at": "2025-12-01T11:01:10.986966Z",
  "credit_cost": 374,
  "message": null,
  "artifact_url": null
}

Response (running):

{
  "id": "abc123-def456-ghi789",
  "status": "running",
  "step": "Analyzing highlights",
  "webhook_url": null,
  "created_at": "2025-12-01T11:01:09.745640Z",
  "updated_at": "2025-12-01T11:06:07.341136Z",
  "credit_cost": 374,
  "message": null,
  "artifact_url": null
}

Response (completed):

{
  "id": "abc123-def456-ghi789",
  "status": "completed",
  "step": "Completed",
  "webhook_url": null,
  "created_at": "2025-12-01T11:01:09.745640Z",
  "updated_at": "2025-12-01T11:15:06.536314Z",
  "credit_cost": 374,
  "message": null,
  "artifact_url": "https://viddyflow-runs.s3.amazonaws.com/runs/abc123-def456-ghi789/viddyflow_results_abc123-def456-ghi789.zip?...",
  "artifacts_expires_at": "2025-12-31T11:15:06.536314Z",
  "artifact_retention_days": 30
}

Status values: pending, running, completed, failed

Notice: The platform automatically calculates VOD duration. Download your results from artifact_url when status is completed.

Get Job Results

GET /api/jobs/:job_id/results

Get detailed information about generated highlight videos, shorts, and metadata. Returns only public-facing data - internal processing details like model configurations are filtered out.

Response (summary):

{
  "id": "abc123-def456-ghi789",
  "status": "completed",
  "result_manifest": {
    "summary": {
      "total_videos": 1,
      "generated_video_duration_seconds": 306.973,
      "total_shorts": 5,
      "thumbnails_generated": 3,
      "metadata_generated": 1,
      "source_vod_duration_seconds": 14590.0
    },
    "highlights": [
      {
        "story": "Epic Gameplay Moment",
        "start": 7846.0,
        "end": 7889.52,
        "duration": 43.52,
        "run_name": "audience"
      }
    ],
    "processed_videos": [
      {
        "run_name": "audience",
        "duration_seconds": 306.973,
        "shorts_count": 5,
        "thumbnail_count": 3
      }
    ]
  },
  "artifact_locations": {
    "run_id": "abc123-def456-ghi789",
    "bucket": "viddyflow-runs",
    "region": "us-east-1",
    "url_expires_at": "2025-12-31T11:15:06.536314Z",
    "assets": {
      "compilation": {
        "url": "https://artifacts.viddyflow.com/runs/abc123-def456-ghi789/compilation.mp4?X-Amz-Signature=...",
        "key": "runs/abc123-def456-ghi789/compilation.mp4",
        "size_bytes": 45234567,
        "relative_path": "compilation.mp4"
      },
      "short": [
        {
          "url": "https://artifacts.viddyflow.com/runs/abc123-def456-ghi789/shorts/1.mp4?X-Amz-Signature=...",
          "key": "runs/abc123-def456-ghi789/shorts/1.mp4",
          "size_bytes": 12345678,
          "relative_path": "shorts/1.mp4"
        }
      ],
      "metadata": {
        "url": "https://artifacts.viddyflow.com/runs/abc123-def456-ghi789/metadata.json?X-Amz-Signature=...",
        "key": "runs/abc123-def456-ghi789/metadata.json",
        "size_bytes": 4567,
        "relative_path": "metadata.json"
      }
    },
    "zip_download_url": "https://artifacts.viddyflow.com/runs/abc123-def456-ghi789/viddyflow_results_abc123-def456-ghi789.zip?X-Amz-Signature=..."
  },
  "parameters": {
    "vod_url": "https://twitch.tv/videos/123456789",
    "streamer_name": "StreamerName",
    "game_name": "Game Name",
    "run_profiles": ["audience"],
    "model_preset": "rapid_sprint"
  },
  "created_at": "2025-12-01T11:01:09.745640Z",
  "updated_at": "2025-12-01T11:15:57.924024Z"
}

Structured Access: Individual files are available in artifact_locations.assets. Download compilation videos, shorts, thumbnails, and metadata separately via presigned CDN URLs. Each asset includes relative_path showing its location in the organized folder structure.

Bulk Download: All assets bundled in a single ZIP file available at artifact_locations.zip_download_url. All URLs expire after the time shown in url_expires_at (default: 6 hours).

Webhooks

When creating a job, you can provide a webhook_url to receive notifications when processing completes or fails.

Webhook Payload (completed):

{
  "event": "job.completed",
  "payload": {
    "job_id": "abc123-def456-ghi789",
    "manifest": {
      "summary": {
        "total_videos": 2,
        "generated_video_duration_seconds": 307.725,
        "total_shorts": 9,
        "thumbnails_generated": 6,
        "metadata_generated": 2,
        "source_vod_duration_seconds": 8060.0
      },
      "highlights": [
        {
          "story": "Epic Gameplay Moment",
          "start": 7846.0,
          "end": 7889.52,
          "duration": 43.52,
          "run_name": "balanced"
        }
      ],
      "processed_videos": [
        {
          "run_name": "balanced",
          "duration_seconds": 123.034,
          "shorts_count": 4,
          "thumbnail_count": 3
        },
        {
          "run_name": "streamer",
          "duration_seconds": 184.691,
          "shorts_count": 5,
          "thumbnail_count": 3
        }
      ]
    },
    "artifacts": {
      "assets": {
        "compilation": {
          "url": "https://artifacts.viddyflow.com/runs/abc123-def456-ghi789/balanced/compilation/highlights_balanced.mp4?X-Amz-Signature=...",
          "key": "runs/abc123-def456-ghi789/balanced/compilation/highlights_balanced.mp4",
          "size_bytes": 45234567,
          "relative_path": "balanced/compilation/highlights_balanced.mp4"
        },
        "short": [
          {
            "url": "https://artifacts.viddyflow.com/runs/abc123-def456-ghi789/balanced/shorts/short_01_Epic_Moment.mp4?X-Amz-Signature=...",
            "key": "runs/abc123-def456-ghi789/balanced/shorts/short_01_Epic_Moment.mp4",
            "size_bytes": 12345678,
            "relative_path": "balanced/shorts/short_01_Epic_Moment.mp4"
          }
        ],
        "metadata": {
          "url": "https://artifacts.viddyflow.com/runs/abc123-def456-ghi789/balanced/compilation/balanced_metadata.json?X-Amz-Signature=...",
          "key": "runs/abc123-def456-ghi789/balanced/compilation/balanced_metadata.json",
          "size_bytes": 4567,
          "relative_path": "balanced/compilation/balanced_metadata.json"
        },
        "thumbnail": [
          {
            "url": "https://artifacts.viddyflow.com/runs/abc123-def456-ghi789/balanced/thumbnails/thumb_01.jpg?X-Amz-Signature=...",
            "key": "runs/abc123-def456-ghi789/balanced/thumbnails/thumb_01.jpg",
            "size_bytes": 234567,
            "relative_path": "balanced/thumbnails/thumb_01.jpg"
          }
        ]
      },
      "zip_download_url": "https://artifacts.viddyflow.com/runs/abc123-def456-ghi789/viddyflow_results_abc123-def456-ghi789.zip?X-Amz-Signature=...",
      "url_expires_at": "2025-12-09T15:25:44.537163+00:00"
    }
  }
}

Individual Downloads: The webhook payload includes separate download links for each generated asset (compilation videos, shorts, thumbnails, metadata). Each asset includes a presigned CDN URL, file size, and relative path organized by run type.

Bulk Download: A combined ZIP file containing all assets is available via artifacts.zip_download_url. All URLs expire after the time shown in url_expires_at.

Webhook Payload (failed):

{
  "event": "job.failed",
  "job_id": "abc123-def456-ghi789",
  "status": "failed",
  "error_message": "VOD no longer available",
  "failed_at": "2025-12-01T11:05:30.123456Z"
}

Rate Limits

Rate limit: 60 requests per minute per API key. Contact support if you need higher throughput.

Credit System

ViddyFlow uses a credit-based pricing model for transparent and flexible billing.

Processing Costs

Credits are consumed based on the source video duration and selected processing tier. For example, a 4-hour VOD processed with Rapid Sprint (18 credits/hour) costs approximately 72 credits base cost.

Purchase Credits

Credits can be purchased through monthly subscriptions or one-time top-ups. All plans include full API access and webhook support.

Support & Contact

Need help? We're here for you.

• Email: support@viddyflow.com

• Dashboard: app.viddyflow.com

• Contact: Contact us