MakeUGC Platform API Documentation

Overview

The MakeUGC Platform API allows partners to programmatically generate AI-powered videos using our platform. This documentation provides details on authentication, endpoints, and usage examples.

Authentication

All API requests require authentication using an API key. Include your API key in the request headers:

X-Api-Key: YOUR_API_KEY

Base URL

https://app.makeugc.ai/api/platform

Endpoints

1. Get Available Avatars

Retrieve a list of available avatars (both template and custom).

GET /video/avatars

Query Parameters:

Response:

{
  "status": true,
  "message": "Avatars fetched",
  "data": [
    {
      "id": "avatar_123",
      "name": "Avatar Name",
      "thumbnail": "https://...",
      "gender": "Male"
    }
  ]
}

Status Codes:

2. Get Available Voices

Retrieve a list of available voices (template voices and the current user's custom voices).

GET /video/voices

Query Parameters:

Response:

{
  "status": true,
  "message": "Voices fetched",
  "data": [
    {
      "id": "voice_123",
      "name": "Voice Name",
      "language": "English",
      "gender": "Female",
      "templateUrl": "https://...",
      "thumbnail": "https://...",
      "voiceId": "internal_tts_voice_id",
      "accent": "US",
      "country": "United States",
      "isCustom": false
    }
  ]
}

Status Codes:

3. Video Generation

Generate Video

Creates a new AI video with specified avatar and voice script.

POST /video/generate

Request Body:

{
  "avatar_id": "string",     // Required: ID of the avatar to use
  "voice_script": "string",  // Required: Script for the voice (max 1500 chars)
  "video_name": "string",    // Optional: Custom name for the video (defaults to "API Generated Video")
  "voice_url": "string",     // Optional: URL to existing audio (if provided, skip voice generation; max duration 120s)
  "voice_id": "string",      // Optional: ID Voice actor, if not provide -> using voice default of avatar template
  "voice_settings": {        // Optional: Voice generation settings
    "stability": 0.75,       // Range: 0-1
    "similarity_boost": 0.4, // Range: 0-1
    "style": 0,             // Range: 0-1
    "use_speaker_boost": true
  },
  "webhook_url": "string"    // Optional: Webhook URL for status callbacks
}

Audio source priority: voice_url → voice_id → avatar default voice. If voice_url is invalid/inaccessible or duration is greater than 120 seconds, the request is rejected.

Response:

{
  "status": true,
  "message": "Video generation started",
  "data": {
    "id": "video_123"  // Use this ID to check video status
  }
}

Status Codes:

Check Video Status

Check the status of a video generation request.

GET /video/status

Query Parameters:

Response:

{
  "status": true,
  "message": "Video is processing",
  "data": {
    "status": "processing" | "completed" | "failed",
    "url": "https://..." // Present when status is "completed"
  }
}

Status Codes:

Rate Limits

Important Notes

4. Custom Avatar

Generate Custom Avatar

Create a custom avatar from an image and optional voice sample. Uses multipart/form-data.

POST /custom-avatar/generate

Request Body (multipart/form-data):

image    (required)  — Image file (max 10MB) or URL string
voice    (optional)  — Voice audio file (max 10MB) or URL string

Input flexibility: Both image and voice accept either a direct file upload or a publicly accessible URL string. Files are uploaded to S3 automatically.

Response:

{
  "status": true,
  "data": {
    "status": true,
    "message": "Custom avatar created",
    "avatar_id": "avatar_456",
    "thumbnail_url": "https://...",
    "audio_url": "https://...",
    "selected_voice_id": "voice_789"
  }
}

Status Codes:

Rate Limits

Important Notes

5. Product-in-Hand Generation

Generate Product-in-Hand videos dynamically using different models.

Generate (Nova V2)

POST /product-in-hand/nova-v2/generate

Model limits: Audio duration max 90 seconds.

Request Body:

{
  "image_url": "string",     // Required: Image URL of the product/subject
  "script": "string",        // Required (if voice_url missing): Script for TTS
  "voice_url": "string",     // Optional: Direct audio URL (skips TTS generation)
  "voice_id": "string",      // Required (if voice_url missing): Voice actor ID
  "project_id": "string",    // Optional: Project ID
  "webhook_url": "string"    // Optional: Webhook URL for status callbacks
}

Response:

{
  "status": true,
  "message": "Video generation started",
  "data": { "id": "video_123" }
}

Credits: 1 credit per generation.

Generate (Omi-Human)

POST /product-in-hand/omi-human/generate

Model limits: Audio duration max 30 seconds.

Request Body:

// Same as Nova V2 payload.
// image_url is required, along with either voice_url OR script.
// webhook_url is also supported.

Credits (Dynamic pricing):
< 15s : 1 credit
15s - 30s : 2 credits

Generate (Veo)

POST /product-in-hand/veo/generate

Request Body:

{
  "image_url": "string",     // Required: Video thumbnail/first-frame URL
  "project_id": "string",    // Optional: Project ID
  "model": "string",         // Optional: "pro" or "fast"
  "voice_id": "string",      // Optional: TTS Voice ID
  "end_image_url": "string", // Optional: Target ending frame URL
  "scenes": [                // Required: Array (1-4 scenes)
    {
      "script": "string",
      "description": "string"
    }
  ],
  "webhook_url": "string"    // Optional: Webhook URL for status callbacks
}

Credits: scenes.length * (model === 'pro' ? 2 : 1)

Get Status

GET /product-in-hand/status?id={video_id}

Retrieve the status of a generated PIH video.

Response (Processing):

{
  "status": true,
  "message": "Video is processing",
  "data": { "status": "processing" }
}

Response (Completed):

{
  "status": true,
  "message": "Video is completed",
  "data": {
    "status": "completed",
    "url": "https://cloudfront.net/signed-url.mp4"
  }
}

Response (Failed):

{
  "status": true,
  "message": "Video is failed",
  "data": {
    "status": "failed",
    "reason": "Request timeout due to high load"
  }
}

Support

For API support or questions, please contact: