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

Generate a video

POST /seedance/generate

Send Content-Type: application/json. Only the fields below are accepted.

• model (required): one of the model IDs above.
• prompt (required): non-empty text, at most 15,000 Unicode characters.
• project_id (optional): an existing project owned by your API-key account. If omitted, a project is created automatically.
• duration (optional, default 10): integer seconds within the model's range, or -1 for Auto. Send a JSON number, not a string.
• aspect_ratio (optional, default 9:16): 9:16, 16:9, 4:3, 3:4, 1:1, 21:9, or adaptive.
• resolution (optional, default 720p): a supported resolution for the selected model.
• generate_audio (optional, default true): whether to generate output audio.
• image_url (optional): one reference image URL.
• image_urls (optional): a non-empty array of reference image URLs, up to the model limit. Use either image_url or image_urls. Images guide the generation; these are not first/last frame controls.
• audio_url (optional): one reference audio URL. On 2.0, include at least one image; on 2.5, audio can be used with just the prompt. Reference audio is trimmed to 15s (2.0) or 30s (2.5).
• webhook_url (optional): an HTTP(S) notification URL. The status endpoint below provides the normalized generation result and can also be used alongside notifications.

Reference URLs must use HTTP(S) and remain accessible without login during processing. Upload files first and pass their URLs; base64, asset://, video references, and video editing are not accepted by this endpoint.

Example: text to video (Seedance 2.0 Pro)

curl -X POST 'https://app.makeugc.ai/api/platform/seedance/generate' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "seedance-2.0",
    "prompt": "A cinematic sunrise over a misty mountain lake",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": true
  }'

For 2.0 Fast, change model to seedance-2.0-fast.

Example: image and audio references (Seedance 2.5)

curl -X POST 'https://app.makeugc.ai/api/platform/seedance/generate' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "seedance-2.5",
    "prompt": "Create a product showcase using these references",
    "image_urls": ["https://your-cdn.example/product.jpg"],
    "audio_url": "https://your-cdn.example/reference.mp3",
    "duration": 20,
    "resolution": "1080p",
    "aspect_ratio": "9:16"
  }'

Response (HTTP 200, generation accepted)

{
  "status": true,
  "message": "Video generation started",
  "data": {
    "id": "video-id",
    "project_id": "project-id",
    "model": "seedance-2.0",
    "status": "processing",
    "estimated_credits": 1.1,
    "credits_charged": 1.1
  }
}

Save data.id for polling. A successful POST means the job was accepted, not that the video is ready. Each POST starts a new job; avoid blindly retrying a submission after a timeout, which could create a duplicate generation.

Get status

GET /seedance/status?id={id}

curl 'https://app.makeugc.ai/api/platform/seedance/status?id=VIDEO_ID' \
  -H 'X-Api-Key: YOUR_API_KEY'

Poll every 5–10 seconds until completed or failed. You can only retrieve Seedance videos owned by your API-key account.

Processing

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

Completed

{ "status": true, "message": "Video is completed", "data": { "id": "video-id", "status": "completed", "url": "https://cdn.example/video.mp4" } }

url may be null if the output is not yet available; poll again to retrieve it.

Failed

{ "status": true, "message": "Video is failed", "data": { "id": "video-id", "status": "failed", "reason": "Video generation failed" } }

The outer status indicates that the API request succeeded; data.status indicates the generation outcome.