MakeUGC Platform API Documentation

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:

• 200 Success
• 400 Missing required fields or invalid input
• 401 Not authenticated
• 404 Avatar or voice not found
• 500 Server error

Check Video Status

Check the status of a video generation request.

GET /video/status

Query Parameters:

• id: Video ID (required)

Response:

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

Status Codes:

• 200 Success
• 400 Missing video ID
• 401 Not authenticated
• 404 Video not found
• 500 Server error

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:

• 200 Success
• 400 Missing image, invalid file type, file too large, or insufficient credits
• 401 Not authenticated
• 404 Subscription not found
• 500 Server error

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

List packs

GET /shopable/packs

Categories, allowed formats, and defaults.

Generate image

POST /shopable/images

{
  "category": "general",
  "format": "kinetic_start_frame",
  "context": "premium clean tone, product hero",
  "image_url": "https://cdn.example.com/product.png",
  "aspect_ratio": "9:16"
}

Poll: GET /shopable/images/status?id={id}

Generate video

POST /shopable/videos

{
  "category": "general",
  "format": "kinetic_packshot",
  "context": "premium product motion, clean CTA",
  "image_urls": ["https://cdn.example.com/product.png"],
  "duration": "7",
  "aspect_ratio": "9:16"
}

Poll: GET /shopable/videos/status?id={id}

Normalized status matches Product-in-Hand (processing / completed / failed + url).

List Templates

GET /content-library/templates

Query Parameters:

• category — Filter by category (default: all). Returns all matching templates.

Response:

{
  "status": true,
  "message": "Templates retrieved successfully",
  "data": [
    {
      "id": "template_uuid",
      "title": "Template title",
      "description": "...",
      "credit": "1",
      "preview_url": "https://...",
      "category": ["hook", "ugc"],
      "require_fields": {
        "product_name": { "type": "input", "label": "Product name" },
        "product_image": { "type": "image", "label": "Product image" },
        "script": { "type": "textarea", "label": "Script", "max": 400 }
      }
    }
  ]
}

List Categories

GET /content-library/categories

Response:

{
  "status": true,
  "message": "Categories retrieved successfully",
  "data": [
    { "label": "All", "value": "all" },
    { "label": "hook", "value": "hook" }
  ]
}

Generate Video

POST /content-library/generate

Start a video generation job from a template. Dynamic body fields must match require_fields from the list templates response.

Request Body:

{
  "template_id": "string",       // Required: Template UUID from list templates
  "project_id": "string",        // Optional: Auto-creates a project if omitted
  "webhook_url": "string",       // Optional: HTTPS URL for terminal job callbacks (see Webhook Callback)
  "product_name": "string",      // Example dynamic field (input)
  "product_image": "string",     // Example dynamic field (image) — must be public https URL
  "script": "string"             // Example dynamic field (textarea)
}

Notes:

• All keys defined in require_fields for the template are required.
• image type fields must be valid http:// or https:// URLs (no file upload on this API).
• Credits are deducted based on the template credit value.
• If webhook_url is set, you may receive a terminal callback in addition to polling GET /content-library/status.

Response:

{
  "status": true,
  "message": "Video generation started",
  "data": { "db_id": "uuid" }
}

Webhook Callback

When webhook_url is provided on generate, your endpoint receives an HTTP POST with Content-Type: application/json when the job reaches a terminal state. Use polling if you need a guaranteed delivery or miss a callback.

video_id in the payload corresponds to the db_id returned from generate.

Payload (completed):

{
  "event": "video2video.job.terminal",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "video_id": "660e8400-e29b-41d4-a716-446655440001",
  "status": "completed",
  "user_id": "user_123",
  "project_id": "proj_456",
  "template_id": "tpl_789",
  "template_type": "hook",
  "pipeline_id": "hook_default",
  "video_url": "https://s3.amazonaws.com/.../final.mp4",
  "thumbnail_url": "https://s3.amazonaws.com/.../thumb.jpg",
  "error": null,
  "completed_at": "2026-05-28T12:34:56.789123+00:00"
}

Payload (failed):

{
  "event": "video2video.job.terminal",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "video_id": "660e8400-e29b-41d4-a716-446655440001",
  "status": "failed",
  "user_id": "user_123",
  "project_id": "proj_456",
  "template_id": "tpl_789",
  "template_type": "hook",
  "pipeline_id": "hook_default",
  "video_url": null,
  "error": "Bootstrap validation failed: missing required field prompt",
  "completed_at": "2026-05-28T12:34:56.789123+00:00"
}

Payload (timed out):

{
  "status": "timed_out",
  "video_url": null,
  "error": "Job exceeded watchdog deadline"
}

Get Status

GET /content-library/status?id={db_id}

Poll generation status using the db_id returned from generate.

Response (Processing):

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

Response (Completed):

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

Response (Failed):

{
  "status": true,
  "message": "Video is failed",
  "data": {
    "db_id": "uuid",
    "status": "failed",
    "reason": "Video generation failed"
  }
}