Video Generation

Video Generation API

Create short video clips from static images, including animations and face swapping.

Base URL

https://api.realm.ai/v1/videos

Job Status

Similar to image generation, video tasks are asynchronous. Use the GET /jobs/{jobId} endpoint (described below) to poll for completion status and retrieve results.

Possible statuses: queued, processing, completed, failed.

Generate Video (Image-to-Video)

Animates a source image to create a short video clip. Various animation styles might be available.

  • Method: POST

  • Endpoint: /generate

  • Authentication: API Key

  • Content-Type: multipart/form-data

Request Body Parameters

  • sourceImage (file): The input image file (JPEG, PNG) to animate.

  • animationType (string, optional, default: 'standard_motion'): Type of animation (e.g., 'standard_motion', 'zoom_in', 'pan_left').

  • durationSeconds (int, optional, default: 4): Desired video duration.

  • fps (int, optional, default: 24): Frames per second.

  • motionStrength (float, optional, 0.0-1.0): Intensity of the animation effect.

Response 202 Accepted

{
  "jobId": "job_vid_gen_789",
  "status": "queued"
}

Perform Face Swap (Image/Video)

Swaps the face from a source image or video onto a target image or video.

  • Method: POST

  • Endpoint: /faceswap

  • Authentication: API Key

  • Content-Type: multipart/form-data

Request Body Parameters

  • sourceFace (file): Image file containing the face to use (JPEG, PNG).

  • targetMedia (file): Image or video file (JPEG, PNG, MP4, MOV) onto which the face will be swapped.

  • enhanceQuality (boolean, optional, default: true): Apply post-processing to improve quality.

  • detectMultipleFaces (boolean, optional, default: false): If target has multiple faces, attempt to swap onto the most prominent one (or specify index if API supports).

Response 202 Accepted

{
  "jobId": "job_vid_swap_101",
  "status": "queued"
}

Get Job Status & Results

Retrieves the status and, upon completion, the results of a video generation or face swap job.

  • Method: GET

  • Endpoint: /jobs/{jobId}

  • Authentication: API Key

Response 200 OK (Processing)

{
  "jobId": "job_vid_gen_789",
  "status": "processing",
  "progressPercent": 40
}

Response 200 OK (Completed)

{
  "jobId": "job_vid_gen_789",
  "status": "completed",
  "result": {
    "videoId": "vid_xyz",
    "url": "https://cdn.realm.ai/videos/vid_xyz.mp4",
    "format": "mp4",
    "durationSeconds": 4
  },
  "completedAt": "2024-03-10T16:15:30Z"
}

Response 200 OK (Failed)

{
  "jobId": "job_vid_swap_101",
  "status": "failed",
  "errorCode": "FACE_NOT_DETECTED",
  "errorMessage": "Could not detect a face in the source image.",
  "failedAt": "2024-03-10T16:20:00Z"
}
PreviousImage GenNextAuthentication

Last updated