DEV Community: Magic Hour

Lip-sync APIs when you already have the voice recording

Magic Hour — Sun, 08 Nov 2026 23:08:59 +0000

Magic Hour publishes this comparison and provides two of the routes below. AI generated the writing from the cited documentation. The examples compare input contracts. They do not report render tests or accuracy scores.

If you already have a voice track, start by checking the visual input. Existing footage needs video lip sync. A still portrait needs a talking-photo workflow. A scene with multiple speakers may also need an API that lets you specify who speaks and when.

Input and job	Route to evaluate	What to verify
Existing video plus a replacement recording	Magic Hour Lip Sync, `POST /v1/lip-sync`	Send `video_file_path` and `audio_file_path` in `assets`. The request's start and end times select the video clip.
A still portrait plus a recording	Magic Hour AI Talking Photo, `POST /v1/ai-talking-photo`	Send `image_file_path` and `audio_file_path` in `assets`. Start with one visible face.
Existing footage where you need speaker or segment controls	Sync Labs, `POST /v2/generate`	Its documentation covers typed video and audio inputs, speaker selection and segment controls. Check the options for your chosen model before building the UI.

Magic Hour Lip Sync schema · Magic Hour Talking Photo schema · Sync Labs generation schema · Sync Labs segment controls

One input change switches the workflow

This five-second example uses Magic Hour's video lip-sync route. Replace the example paths with files uploaded for your account.

{
  "start_seconds": 0,
  "end_seconds": 5,
  "assets": {
    "video_source": "file",
    "video_file_path": "api-assets/id/speaker.mp4",
    "audio_file_path": "api-assets/id/new-voice.wav"
  }
}

If you have a portrait instead of footage, send image_file_path and audio_file_path to the talking-photo endpoint. Dropping an image into the video field would ask the wrong route to do the job. Magic Hour upload flow

Decide what counts as usable

Try an authorized five-second excerpt with a clear view of the speaker's mouth and a clean recording. Compare mouth motion at the first word, the hardest phrase and the last word.
In a multi-speaker scene, check the people who should remain unchanged. Confirm whether the documented controls apply to your model before promising automatic speaker selection.
Download the completed artifact and check the actual audio duration and alignment. Keep API completion separate from your review result. One passing clip is a starting point for testing harder footage.

Magic Hour video status and downloads · Sync Labs speaker selection

Image-to-video APIs for start and end frames: what to check before you build

Magic Hour — Sun, 08 Nov 2026 23:07:46 +0000

Magic Hour publishes this comparison and provides one of the APIs below. AI generated the writing from the cited documentation. This is a request-schema comparison, with no renders or timing tests.

A start frame gives a video model a picture to animate. An end frame tells it where to land. If you need a product reveal to finish on a particular composition, confirm that the selected model accepts an end frame at the resolution you sell before building the rest of the workflow.

Route	Start image	End image	Where to check the result
Magic Hour Image-to-Video	`assets.image_file_path`	`assets.end_image_file_path`, with model-specific resolution support	Save the project ID and retrieve the completed project's `downloads`.
fal Kling 3.0 Pro	`start_image_url`	`end_image_url`	Save the request ID, then get the queue result and read its `video` output.
Runway Image-to-Video	The API accepts a `promptImage` URL or positioned image inputs according to the model.	Confirm the selected model's documented input schema before treating `last` as available.	Save the task ID and retrieve task status and output.

Magic Hour Image-to-Video schema · fal Kling 3.0 Pro schema · Runway API reference

Example request for a five-second reveal

This is the JSON body for Magic Hour's POST /v1/image-to-video. Replace both sample paths with your own uploaded file paths. The request uses the documented ltx-2.5 route with a 720p output. A real request consumes credits.

{
  "end_seconds": 5,
  "model": "ltx-2.5",
  "resolution": "720p",
  "audio": false,
  "style": {
    "prompt": "Reveal the product slowly, then settle on the final composition."
  },
  "assets": {
    "image_file_path": "api-assets/id/start.png",
    "end_image_file_path": "api-assets/id/end.png"
  }
}

Before sending the job, reject unsupported model and resolution combinations in your form. For example, the Magic Hour docs list 1080p for the Kling 2.6 end-frame input and 480p, 720p, and 1080p for LTX 2.5. The same field can have different rules across models. Keep a link to the current schema beside your adapter so it is easy to update those rules. End-frame limits · Upload file paths

Check the delivered clip against the input

Use start and end images with the same intended crop. Compare the last usable frame with the end image at delivery size.
For a product shot, check the shape, logo, label and color through the transition. An endpoint accepting an end frame gives you a control to test. The downloaded clip still needs to pass your own checks.
Save the job ID, model, resolution, both input references and the final charge. If the render finishes but fails review, record that separately from a failed API job. This lets you compare cost per accepted reveal once you have enough attempts.

Magic Hour completed video details · fal queue API · Runway task workflow

Best Video Face Swap APIs for Production: Setup, Cost per Finished Clip, and Failure Handling

Magic Hour — Sun, 08 Nov 2026 22:45:40 +0000

Magic Hour publishes this guide and provides one of the APIs below. This article was generated with AI from the cited documentation. The comparison is based on public endpoint documentation checked November 8, 2026. It does not report a head-to-head render test or measured latency.

A face swap API can accept your request without producing a clip you can use. Before choosing one, check which face it targets, how it reports a finished result, and what you pay for the clips that make it through your own review.

If you need	Start with	Check before building
One API for ordinary video swaps and explicit face mappings	Magic Hour	Direct media URLs or uploaded file paths. The basic request uses `all-faces`; use `individual-faces` with `face_mappings` if different people need different replacements.
A published per-second price and one face selected by size	WaveSpeedAI	Its documented `target_index` selects by face size. Check that this identifies the intended person in your actual footage.
A separate face-detection step before supplying mappings	AKOOL	Its Video Faceswap route accepts a video and `faceMapping` data. Account for the detection step when estimating integration work.

Magic Hour request schema · WaveSpeed model and pricing · AKOOL request schema

Compare cost after you can download the result

Start with the same three-second input and the same acceptance criteria. WaveSpeed publishes a $0.01-per-second rate for this route, rounded up to whole seconds with a three-second minimum. Its published formula gives $0.03 for that request, before considering extra attempts. Magic Hour returns credits_charged when it queues the project. Read the completed project and check your account's credit pricing before converting the charge to dollars. Magic Hour documents that failed jobs are refunded. A successful render that you discard for quality is a separate case to track.

For a fair comparison, divide your net charges after applicable refunds by the number of clips that pass review. Include cases where the job completed but chose the wrong face, had visible artifacts, or returned a file you couldn't use. With zero acceptable clips, record zero accepted and the actual spend instead of computing a unit cost. WaveSpeed rate calculation · Magic Hour billing and status · Magic Hour API pricing

Run one Magic Hour request in Node.js

Save the script below as face-swap.mjs and run it with Node.js 20 or newer. Set MAGIC_HOUR_API_KEY, FACE_IMAGE and TARGET_VIDEO in your shell. Each media variable can be a Magic Hour upload file_path or a direct media URL with a supported extension. Use a video of at least three seconds with one visible person. Run with node face-swap.mjs. This submits one billable request. Only use media you have permission to modify.

import { setTimeout as sleep } from 'node:timers/promises';

const token = process.env.MAGIC_HOUR_API_KEY;
const image = process.env.FACE_IMAGE;
const video = process.env.TARGET_VIDEO;
const existingId = process.env.PROJECT_ID;
const base = 'https://api.magichour.ai/v1';

async function request(path, body) {
  const response = await fetch(base + path, {
    method: body ? 'POST' : 'GET',
    headers: {
      Authorization: `Bearer ${token}`,
      ...(body ? { 'Content-Type': 'application/json' } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
    signal: AbortSignal.timeout(15_000),
  });
  if (!response.ok) {
    const error = new Error(`Magic Hour returned HTTP ${response.status}`);
    error.status = response.status;
    throw error;
  }
  return response.json();
}

async function main() {
  if (!token || (!existingId && (!image || !video))) {
    throw new Error('Set MAGIC_HOUR_API_KEY and either PROJECT_ID or both FACE_IMAGE and TARGET_VIDEO.');
  }

  let id = existingId;
  if (!id) {
    const job = await request('/face-swap', {
      name: 'Three-second video face swap',
      start_seconds: 0,
      end_seconds: 3,
      assets: {
        face_swap_mode: 'all-faces',
        image_file_path: image,
        video_source: 'file',
        video_file_path: video,
      },
    });
    id = job.id;
    if (!id) throw new Error('No project ID in the create response. Check the account before resubmitting.');
    console.error(`PROJECT_ID=${id} (queued credits: ${job.credits_charged})`);
  }

  const deadline = Date.now() + 10 * 60_000;
  while (Date.now() < deadline) {
    let job;
    try {
      job = await request(`/video-projects/${encodeURIComponent(id)}`);
    } catch (error) {
      if (!(error.status === 429 || error.status >= 500 ||
            ['TimeoutError', 'TypeError'].includes(error.name))) throw error;
      await sleep(5_000);
      continue;
    }
    if (job.status === 'complete') {
      const url = job.downloads?.[0]?.url;
      if (!url) throw new Error(`Project ${id} is complete but has no download URL.`);
      console.log(JSON.stringify({ id, url, credits: job.credits_charged }));
      return;
    }
    if (!['queued', 'rendering'].includes(job.status)) {
      throw new Error(`Project ${id} reached status ${job.status}. Check project details for the reason.`);
    }
    await sleep(3_000);
  }
  throw new Error(`Stopped waiting. Resume by setting PROJECT_ID=${id}.`);
}

main().catch(error => {
  console.error(error.message);
  process.exitCode = 1;
});

What to do when it stops

The create request timed out. Check the account before resubmitting. The server may have accepted the request even if the response never reached you.
The project ID exists but polling timed out. Save the ID. Set PROJECT_ID and run the script again to check the existing job without creating another one.
The job completed. Fetch the returned file, verify it plays, and inspect the intended face at the hardest frame. For a production workflow, save the project ID and final charge with your own acceptance result. Use a webhook if polling is a poor fit for your worker.

Upload private inputs · Project statuses and download fields · Webhook docs

If a three-second clip passes your review, try the hardest clip before buying volume. Explore the Magic Hour Face Swap API