# AI Script Generation
Source: https://docs.jogg.ai/api-reference/v2/API Documentation/AIScripts

Automatically generate engaging video scripts with AI

## Introduction

Generate professional marketing scripts automatically using JoggAI's AI. Provide product information or a topic, and get multiple script variations optimized for your video length and language. Perfect for scaling video content production across multiple products, languages, and platforms.

### Key Features

<CardGroup>
  <Card title="Auto-Generate" icon="wand-magic-sparkles">
    Create scripts from product info or descriptions
  </Card>

  <Card title="Multiple Styles" icon="sparkles">
    Get 3-5 script variations in different styles
  </Card>

  <Card title="Length Optimization" icon="clock">
    Scripts timed for 15/30/60 second videos
  </Card>

  <Card title="40+ Languages" icon="language">
    Generate scripts in any supported language
  </Card>
</CardGroup>

### Workflow Overview

AI script generation is a **2-step asynchronous process**:

<Steps>
  <Step title="Submit Request">
    Send product info and requirements to AI
  </Step>

  <Step title="Retrieve & Select">
    Get generated scripts and choose your favorite
  </Step>
</Steps>

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant API
    participant AI
    
    Note over Client,AI: Step 1: Submit Request
    Client->>API: POST /v2/ai_scripts {product_info, language, video_length_seconds, script_style}
    API->>AI: Generate scripts
    API-->>Client: 200 OK {task_id}
    
    Note over AI: Processing (10-30s)
    AI->>AI: Generate multiple<br/>script variations
    
    Note over Client,AI: Step 2: Retrieve Results
    Client->>API: GET /v2/ai_scripts/results/{task_id}
    API-->>Client: 200 OK {scripts[]}
```

<Info>
  AI script generation typically completes in **10-30 seconds**. You can start polling after 15 seconds.
</Info>

***

## Quick Start

### Related API Endpoints

| Endpoint                               | Purpose                          | Documentation                                              |
| -------------------------------------- | -------------------------------- | ---------------------------------------------------------- |
| `POST /v2/ai_scripts`                  | Submit script generation request | [API Reference](/api-reference/v2/Asset/CreateAIScript)    |
| `GET /v2/ai_scripts/results/{task_id}` | Get generated scripts            | [API Reference](/api-reference/v2/Asset/GetAIScriptResult) |
| `POST /v2/product`                     | Create product entry             | [API Reference](/api-reference/v2/Product/CreateProduct)   |

### Key Parameters

| Parameter                  | Type   | Required | Description                                                                                |
| -------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `language`                 | string | ✅        | Script language (e.g., "english", "spanish")                                               |
| `video_length_seconds`     | string | ✅        | Video length: "15", "30", or "60"                                                          |
| `script_style`             | string | ✅        | Style: "Don't Worry", "Storytime", "Discovery", "Data", "Top 3 reasons", "Light marketing" |
| `product_info`             | object | ✅        | Product information object                                                                 |
| `product_info.source_type` | string | ✅        | "id" (use product ID) or "details" (provide details)                                       |
| `product_info.data`        | object | ✅        | Product data (varies by source\_type)                                                      |
| `target_audience`          | string | ❌        | Target audience description (optional)                                                     |

<Warning>
  **Product Info Required:** Either provide a `product_info.data.id` (for existing products) or `product_info.data.name` and `product_info.data.description` (for new products).
</Warning>

***

## Code Examples

### Scenario 1: Generate Scripts from Product ID

Use an existing product to generate scripts:

#### Step 1: Submit Script Generation Request

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/ai_scripts' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "language": "english",
    "video_length_seconds": "30",
    "script_style": "Storytime",
    "product_info": {
      "source_type": "id",
      "data": {
        "id": "NTQ0MTkzNjg"
      }
    }
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "task_id": "task_123456789"
  }
}
```

<Check>
  Save the `task_id` - you'll need it to retrieve your scripts!
</Check>

***

#### Step 2: Retrieve Generated Scripts

Wait 15-30 seconds, then retrieve your scripts:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/ai_scripts/results/task_123456789' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response (Completed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "task_id": "task_123456789",
    "status": "completed",
    "data": {
      "generated_scripts": [
        {
          "script_style": "Storytime",
          "script_paragraphs": [
            "Ever tried drinking water while running?",
            "The Owala FreeSip bottle changes everything.",
            "Its unique spout lets you sip or swig - no spills, no fuss.",
            "Plus, it keeps drinks cold for 24 hours.",
            "Perfect for gym, work, or adventures!"
          ]
        },
        {
          "script_style": "Discovery",
          "script_paragraphs": [
            "Discover the Owala FreeSip - the water bottle that adapts to you.",
            "Sip through the straw or tilt to swig from the spout.",
            "Double-wall insulation keeps drinks ice-cold all day.",
            "Available in vibrant colors that match your style!"
          ]
        },
        {
          "script_style": "Top 3 reasons",
          "script_paragraphs": [
            "Three reasons to love the Owala FreeSip:",
            "One, the patented FreeSip spout for sipping or swigging.",
            "Two, 24-hour cold insulation.",
            "Three, leak-proof design for your bag.",
            "Upgrade your hydration game today!"
          ]
        }
      ]
    }
  }
}
```

<Tip>
  The AI generates multiple script variations automatically. Choose the style that best fits your brand and audience!
</Tip>

***

### Scenario 2: Generate Scripts with Product Details

Provide product details directly without creating a product entry:

#### Step 1: Submit Request with Product Details

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/ai_scripts' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "language": "english",
    "video_length_seconds": "30",
    "script_style": "Discovery",
    "product_info": {
      "source_type": "details",
      "data": {
        "name": "Premium Yoga Mat",
        "description": "Eco-friendly yoga mat with superior grip and cushioning. Made from natural rubber with moisture-wicking surface. 6mm thickness provides excellent support."
      }
    },
    "target_audience": "Yoga enthusiasts and fitness lovers"
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "task_id": "task_987654321"
  }
}
```

***

#### Step 2: Retrieve Generated Scripts

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/ai_scripts/results/task_987654321' \
  --header 'x-api-key: YOUR_API_KEY'
```

***

### Scenario 3: Check Generation Status

Poll to check if scripts are ready:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/ai_scripts/results/task_123456789' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response (Still Processing):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "task_id": "task_123456789",
    "status": "processing"
  }
}
```

**Response (Completed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "task_id": "task_123456789",
    "status": "completed",
    "data": {
      "generated_scripts": [...]
    }
  }
}
```

**Response (Failed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "task_id": "task_123456789",
    "status": "failed",
    "err_msg": "Failed to generate script"
  }
}
```

***

## Advanced Examples

### Short 15-Second Scripts

Generate punchy scripts for quick social media videos:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/ai_scripts' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "language": "english",
    "video_length_seconds": "15",
    "script_style": "Light marketing",
    "product_info": {
      "source_type": "id",
      "data": {
        "id": "NTQ0MTkzNjg"
      }
    }
  }'
```

**Sample Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "task_id": "task_123456789",
    "status": "completed",
    "data": {
      "generated_scripts": [
        {
          "script_style": "Light marketing",
          "script_paragraphs": [
            "Meet the Owala FreeSip - your new hydration hero!",
            "Sip or swig with one spout.",
            "Stays cold for 24 hours.",
            "Get yours today!"
          ]
        }
      ]
    }
  }
}
```

***

### Multi-Language Scripts

Generate scripts in different languages:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/ai_scripts' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "language": "spanish",
    "video_length_seconds": "30",
    "script_style": "Storytime",
    "product_info": {
      "source_type": "id",
      "data": {
        "id": "NTQ0MTkzNjg"
      }
    }
  }'
```

**Spanish Script Example:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "task_id": "task_123456789",
    "status": "completed",
    "data": {
      "generated_scripts": [
        {
          "script_style": "Storytime",
          "script_paragraphs": [
            "¿Alguna vez intentaste beber agua mientras corres?",
            "La botella Owala FreeSip lo cambia todo.",
            "Su boquilla única te permite sorber o tragar - sin derrames, sin problemas.",
            "Además, mantiene las bebidas frías durante 24 horas.",
            "¡Perfecto para el gimnasio, trabajo o aventuras!"
          ]
        }
      ]
    }
  }
}
```

<Tip>
  Supported languages include: English, Spanish, French, German, Japanese, Korean, Chinese, Portuguese, and 30+ more. See full list in the [API Reference](/api-reference/v2/Asset/CreateAIScript).
</Tip>

***

## Script Style Guide

Understanding different script styles:

| Style               | Characteristics                     | Best For                                  |
| ------------------- | ----------------------------------- | ----------------------------------------- |
| **Storytime**       | Narrative, engaging, conversational | Products with a journey or transformation |
| **Discovery**       | Exciting, exploratory, unveiling    | New or innovative products                |
| **Don't Worry**     | Reassuring, problem-solving         | Products that solve pain points           |
| **Data**            | Factual, statistics-driven          | Tech products, B2B                        |
| **Top 3 Reasons**   | Clear, structured, benefit-focused  | Feature-rich products                     |
| **Light Marketing** | Friendly, promotional, upbeat       | General products, e-commerce              |

<Info>
  The AI automatically generates scripts in multiple styles so you can choose the best fit for your brand and audience.
</Info>

***

## Use Case Examples

<AccordionGroup>
  <Accordion title="E-commerce Product Descriptions">
    Convert product pages into video scripts:

    * Use existing product IDs
    * Generate in multiple languages for global markets
    * Create variations for A/B testing
    * Batch process entire catalog
  </Accordion>

  <Accordion title="Social Media Content">
    Create engaging scripts for social platforms:

    * Use 15-second scripts for TikTok/Reels
    * Try "Storytime" or "Discovery" styles
    * Generate in target market languages
    * Produce multiple versions weekly
  </Accordion>

  <Accordion title="Ad Campaign Copy">
    Generate ad scripts quickly:

    * Test different messaging angles
    * Create urgency with "Don't Worry" style
    * Use "Top 3 Reasons" for clarity
    * Localize for different regions
  </Accordion>

  <Accordion title="Content Marketing">
    Scale video content production:

    * Generate scripts for product series
    * Create educational content
    * Produce weekly tips and tricks
    * Maintain consistent messaging
  </Accordion>
</AccordionGroup>

***

## Tips for Best Results

<Tip>
  **Script Selection:**

  * Match your brand voice by selecting style that aligns with brand personality
  * Know your audience: "Data" style for B2B, "Storytime" for consumers
  * Consider platform: Shorter, punchier scripts for social media
  * Test different styles: A/B test to find what resonates
</Tip>

**Optimization Tips:**

* **Be specific** with product descriptions for better results
* **Include key features** you want highlighted
* **Specify target audience** for appropriate tone
* **Generate multiple times** if not satisfied with first result
* **Provide detailed descriptions** when using `source_type: "details"`

**Best Practices:**

* Wait 15-30 seconds before checking results
* Use product IDs when possible for better consistency
* Generate multiple script variations and compare
* Test different styles for the same product
* Use appropriate video length for your platform

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Scripts are too generic">
    **Issue:** Generated scripts lack specificity

    **Solutions:**

    * Provide more detailed product descriptions
    * Include specific features and benefits
    * Specify target audience clearly
    * Add unique selling points
    * Use `target_audience` parameter
  </Accordion>

  <Accordion title="Wrong language or tone">
    **Issue:** Scripts don't match expected language or style

    **Solutions:**

    * Verify `language` parameter is correct
    * Try different `script_style` options
    * Provide `target_audience` description
    * Add context about brand personality in product description
    * Check language spelling (e.g., "english" not "English")
  </Accordion>

  <Accordion title="Task stays in processing">
    **Issue:** Script generation takes longer than expected

    **Solutions:**

    * Wait up to 60 seconds before retry
    * Check `task_id` is correct
    * Verify API key permissions
    * Check product ID exists (if using `source_type: "id"`)
    * Contact support if persists > 2 minutes
  </Accordion>

  <Accordion title="No scripts generated">
    **Issue:** Response shows completed but no scripts

    **Solutions:**

    * Check `data.generated_scripts` array in response
    * Verify product information is valid
    * Ensure product description is detailed enough
    * Try with different `script_style`
    * Retry with simpler product description
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Create Product" icon="box" href="/api-reference/v2/Product/CreateProduct">
    Create product entries first
  </Card>

  <Card title="Avatar Videos" icon="user" href="/api-reference/v2/API Documentation/CreateAvatarVideos">
    Use scripts in avatar videos
  </Card>

  <Card title="Product Videos" icon="video" href="/api-reference/v2/API Documentation/URLtoVideo">
    Generate videos with AI scripts
  </Card>

  <Card title="Webhook Integration" icon="webhook" href="/api-reference/v2/API Documentation/WebhookIntegration">
    Automate script generation
  </Card>
</CardGroup>


# Avatar Videos with Transparent Background
Source: https://docs.jogg.ai/api-reference/v2/API Documentation/AvatarVideosTransparentBackground

Generate avatars with transparent backgrounds for easy compositing

## Introduction

Create avatar videos with transparent backgrounds (alpha channel) for easy compositing over other content. Perfect for presentations, video editing, or web applications.

### Key Features

<CardGroup>
  <Card title="Green Screen" icon="film">
    Chroma key background for video editing
  </Card>

  <Card title="Alpha Channel" icon="image">
    True transparency with WebM format
  </Card>

  <Card title="Easy Compositing" icon="layer-group">
    Overlay on any background
  </Card>

  <Card title="Professional Editing" icon="wand-magic">
    Works with all major video editors
  </Card>
</CardGroup>

<Info>
  **Best for:** Overlaying avatars on presentations, adding to existing videos, website backgrounds, video editing projects, green screen replacements, and AR/VR applications.
</Info>

***

## Quick Start

### Related API Endpoints

| Endpoint                         | Purpose                                  | Documentation                                                  |
| -------------------------------- | ---------------------------------------- | -------------------------------------------------------------- |
| `POST /create_video_from_avatar` | Create video with transparent background | [API Reference](/api-reference/v2/Video/CreateVideoFromAvatar) |
| `GET /avatar_video/{id}`         | Check video status                       | [API Reference](/api-reference/v2/Video/AvatarVideoGet)        |

### Key Parameters

| Parameter            | Type    | Required | Description                                                                  |
| -------------------- | ------- | -------- | ---------------------------------------------------------------------------- |
| `screen_style`       | integer | ✅        | **2** = Split screen (green screen), **3** = Picture in picture (WebM alpha) |
| `avatar.avatar_id`   | integer | ✅        | Choose full-body avatar for best results                                     |
| `avatar.avatar_type` | integer | ✅        | 0=Public, 1=Custom                                                           |
| `voice.type`         | string  | ✅        | "script" for text-to-speech                                                  |
| `voice.voice_id`     | string  | ✅        | Voice ID for text-to-speech                                                  |
| `voice.script`       | string  | ✅        | Text for avatar to speak                                                     |
| `aspect_ratio`       | string  | ✅        | portrait/landscape/square                                                    |

**Output Formats:**

* **Split Screen (screen\_style: 2)**: MP4 with green background - use chroma key in video editor
* **Picture in Picture (screen\_style: 3)**: WebM with alpha channel - true transparency, no keying needed

***

## Code Examples

### Scenario 1: Green Screen (Split Screen)

Create video with green screen for video editing:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_from_avatar' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "avatar": {
      "avatar_id": 81,
      "avatar_type": 0
    },
    "voice": {
      "type": "script",
      "voice_id": "en-US-ChristopherNeural",
      "script": "Welcome! This avatar has a transparent background."
    },
    "aspect_ratio": "portrait",
    "screen_style": 2,
    "caption": false
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456"
  }
}
```

**Use for:**

* Video editing software (Premiere, Final Cut, DaVinci)
* Broadcast applications
* Maximum compatibility

**How to use:**

1. Import video to editor
2. Apply chroma key effect
3. Remove green color
4. Composite over background

***

### Scenario 2: WebM with Alpha Channel

Create video with true transparency:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_from_avatar' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "avatar": {
      "avatar_id": 81,
      "avatar_type": 0
    },
    "voice": {
      "type": "script",
      "voice_id": "en-US-ChristopherNeural",
      "script": "Your script here"
    },
    "aspect_ratio": "portrait",
    "screen_style": 3
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456"
  }
}
```

**Use for:**

* Web applications
* HTML5 video players
* Direct compositing without keying

**How to use:**

```html theme={null}
<video autoplay loop muted playsinline>
  <source src="avatar-transparent.webm" type="video/webm">
</video>
```

<Check>
  Set `screen_style: 2` for green screen (video editing) or `screen_style: 3` for WebM with alpha channel (web applications).
</Check>

***

## Use Case Examples

<AccordionGroup>
  <Accordion title="Video Editing Projects">
    Composite avatars into existing videos:

    * Use green screen format (screen\_style: 2)
    * Import to Premiere, Final Cut, or DaVinci
    * Apply chroma key effect
    * Overlay on any background
  </Accordion>

  <Accordion title="Web Applications">
    Add avatars to websites:

    * Use WebM with alpha (screen\_style: 3)
    * Embed in HTML5 video player
    * Overlay on dynamic backgrounds
    * No keying required
  </Accordion>

  <Accordion title="Presentations">
    Add avatars to slides:

    * Create transparent avatar videos
    * Overlay on presentation slides
    * Professional appearance
    * Easy to update
  </Accordion>

  <Accordion title="AR/VR Applications">
    Use avatars in immersive experiences:

    * WebM with alpha channel
    * True transparency
    * Composite in 3D environments
    * Realistic integration
  </Accordion>
</AccordionGroup>

***

## Tips for Best Results

<Tip>
  **Quality Tips:**

  * Use full-body avatars for best results
  * Test composite in target environment
  * For web, use WebM with alpha (screen\_style: 3)
  * For video editing, use green screen (screen\_style: 2)
  * Avoid captions if compositing over text-heavy backgrounds
  * Green screen works best with even lighting
  * WebM alpha has cleaner edges
</Tip>

***

## Related Documentation

<CardGroup>
  <Card title="Create Avatar Videos" icon="user" href="/api-reference/v2/API Documentation/CreateAvatarVideos">
    Main avatar video guide
  </Card>

  <Card title="Get Avatar Video" icon="video" href="/api-reference/v2/Video/AvatarVideoGet">
    Check video generation status
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/v2/Video/CreateVideoFromAvatar">
    Complete API documentation
  </Card>

  <Card title="Get Avatars" icon="users" href="/api-reference/v2/Avatar/PublicAvatarsGet">
    Browse available avatars
  </Card>
</CardGroup>


# Avatar Videos with Custom Audio
Source: https://docs.jogg.ai/api-reference/v2/API Documentation/AvatarVideosWithAudioSource

Use your own audio file instead of text-to-speech

## Introduction

Use your own audio recordings instead of text-to-speech for complete control over voice, timing, and delivery. Perfect for professional voice-overs, branded audio, or languages not supported by TTS.

### Key Features

<CardGroup>
  <Card title="Custom Voice" icon="microphone">
    Use professional voice talent recordings
  </Card>

  <Card title="Full Control" icon="sliders">
    Control timing, tone, and delivery
  </Card>

  <Card title="Brand Voice" icon="palette">
    Maintain consistent brand audio identity
  </Card>

  <Card title="Any Language" icon="language">
    Use audio in any language or dialect
  </Card>
</CardGroup>

<Info>
  **When to Use:** Best for professional voice-overs, branded audio, dialects not supported by TTS, or when you need precise control over delivery.
</Info>

***

## Quick Start

### Related API Endpoints

| Endpoint                         | Purpose                 | Documentation                                                  |
| -------------------------------- | ----------------------- | -------------------------------------------------------------- |
| `POST /upload/asset`             | Upload audio file       | [API Reference](/api-reference/v2/Asset/UploadAsset)           |
| `POST /create_video_from_avatar` | Create video with audio | [API Reference](/api-reference/v2/Video/CreateVideoFromAvatar) |
| `GET /avatar_video/{id}`         | Check video status      | [API Reference](/api-reference/v2/Video/AvatarVideoGet)        |

### Key Parameters

| Parameter            | Type    | Required | Description                                         |
| -------------------- | ------- | -------- | --------------------------------------------------- |
| `voice.type`         | string  | ✅        | **Must be "audio"** when using audio\_url           |
| `voice.audio_url`    | string  | ✅        | URL of uploaded audio file                          |
| `voice.voice_id`     | string  | ✅        | Voice ID (still required)                           |
| `avatar.avatar_id`   | integer | ✅        | Avatar ID                                           |
| `avatar.avatar_type` | integer | ✅        | 0=Public, 1=Custom                                  |
| `aspect_ratio`       | string  | ✅        | portrait/landscape/square                           |
| `screen_style`       | integer | ✅        | 1=Full screen, 2=Split screen, 3=Picture in picture |

<Warning>
  **Important:** When using `voice.audio_url`, set `voice.type` to "audio" and do NOT include `voice.script`. The `voice.voice_id` is still required.
</Warning>

## Audio Requirements

**Supported Formats:**

* MP3 (recommended)
* WAV
* M4A

**Specifications:**

* Max size: 20MB
* Max duration: 10 minutes
* Recommended bitrate: 192 kbps for music, 128 kbps for voice
* Sample rate: 44.1 kHz

**Quality Tips:**

```bash theme={null}
# Optimize audio with FFmpeg
ffmpeg -i input.wav -codec:a libmp3lame -b:a 192k output.mp3

# Normalize audio levels
ffmpeg -i input.mp3 -filter:a loudnorm output.mp3
```

***

## Code Examples

### Step 1: Get signed URL for upload

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/upload/asset' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "filename": "audio.mp3",
    "content_type": "audio/mpeg"
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "sign_url": "https://storage.jogg.ai/upload/signed-url-here",
    "asset_url": "https://res.jogg.ai/assets/aud_abc123.mp3"
  }
}
```

### Step 2: Upload your file using PUT

```bash theme={null}
curl --request PUT \
  --url 'https://storage.jogg.ai/upload/signed-url-here' \
  --header 'Content-Type: audio/mpeg' \
  --data-binary '@/path/to/audio.mp3'
```

### Step 3: Create video with the audio

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_from_avatar' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "avatar": {
      "avatar_id": 81,
      "avatar_type": 0
    },
    "voice": {
      "type": "audio",
      "voice_id": "en-US-ChristopherNeural",
      "audio_url": "https://res.jogg.ai/assets/aud_abc123.mp3"
    },
    "aspect_ratio": "portrait",
    "screen_style": 1,
    "caption": false
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456"
  }
}
```

<Check>
  Save the `asset_url` from upload response to use as `voice.audio_url`. Video length will automatically match audio duration.
</Check>

### Step 4: Check Video Status

Poll to check if video is ready:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/avatar_video/video_123456' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response (Processing):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456",
    "status": "processing",
    "created_at": 1732806631
  }
}
```

**Response (Completed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456",
    "status": "completed",
    "video_url": "https://res.jogg.ai/videos/video_123456.mp4",
    "cover_url": "https://res.jogg.ai/covers/cover_123456.jpg",
    "created_at": 1732806631
  }
}
```

<Tip>
  Instead of polling, use \[Webhooks]\(/api-reference/v2/API Documentation/WebhookIntegration) to get notified instantly when videos are ready!
</Tip>

***

## Use Case Examples

<AccordionGroup>
  <Accordion title="Professional Voice-Overs">
    Use recordings from professional voice talent:

    * Record in professional studio
    * Upload final edited audio
    * Create videos with consistent voice
    * Maintain professional quality
  </Accordion>

  <Accordion title="Brand Voice">
    Maintain branded audio across videos:

    * Use company spokesperson voice
    * Record once, use in multiple videos
    * Consistent brand audio identity
    * Scale branded content easily
  </Accordion>

  <Accordion title="Multiple Takes">
    Use best take from multiple recordings:

    * Record several versions
    * Upload the best performance
    * Edit audio before uploading
    * Perfect timing and delivery
  </Accordion>

  <Accordion title="Unsupported Languages">
    Use audio in languages not supported by TTS:

    * Record in any language or dialect
    * Upload custom audio
    * Create videos with native speakers
    * Reach diverse audiences
  </Accordion>
</AccordionGroup>

***

## Tips for Best Results

<Tip>
  **Audio Quality:**

  * Use clear speech audio (not music) for best lip sync
  * Ensure audio quality is good (44.1 kHz, 128-192 kbps)
  * Trim silence at start/end
  * Normalize audio levels
  * Check audio language matches avatar capabilities
</Tip>

***

## Related Documentation

<CardGroup>
  <Card title="Create Avatar Videos" icon="user" href="/api-reference/v2/API Documentation/CreateAvatarVideos">
    Main avatar video guide
  </Card>

  <Card title="Upload Media" icon="upload" href="/api-reference/v2/API Documentation/UploadMedia">
    Upload audio files guide
  </Card>

  <Card title="Upload Asset API" icon="code" href="/api-reference/v2/Asset/UploadAsset">
    Complete upload API documentation
  </Card>

  <Card title="Get Avatar Video" icon="video" href="/api-reference/v2/Video/AvatarVideoGet">
    Check video status
  </Card>
</CardGroup>


# Avatar Videos with Photo Avatars
Source: https://docs.jogg.ai/api-reference/v2/API Documentation/AvatarVideosWithPhotoAvatar

Use custom photo avatars created from your own photos

## Introduction

Create personalized avatar videos using custom photo avatars generated from your own portrait photos. Perfect for branded content, personal messaging, or using specific talent.

### Key Features

<CardGroup>
  <Card title="Your Own Face" icon="user">
    Use your own photo to create custom avatars
  </Card>

  <Card title="Brand Consistency" icon="palette">
    Maintain consistent personal or brand presence
  </Card>

  <Card title="Multi-Language" icon="language">
    Same face across 40+ languages
  </Card>

  <Card title="Professional Quality" icon="star">
    High-quality avatar generation from photos
  </Card>
</CardGroup>

<Info>
  **Prerequisites:** You must first create a photo avatar before using it in videos. See \[Create Photo Avatar]\(/api-reference/v2/API Documentation/CreatePhotoAvatar) guide.
</Info>

***

## Quick Start

### Related API Endpoints

| Endpoint                         | Purpose                        | Documentation                                                  |
| -------------------------------- | ------------------------------ | -------------------------------------------------------------- |
| `GET /avatars/photo_avatars`     | Get your photo avatars         | [API Reference](/api-reference/v2/Avatar/PhotoAvatarsGet)      |
| `POST /create_video_from_avatar` | Create video with photo avatar | [API Reference](/api-reference/v2/Video/CreateVideoFromAvatar) |
| `GET /avatar_video/{id}`         | Check video status             | [API Reference](/api-reference/v2/Video/AvatarVideoGet)        |

### Key Parameters

| Parameter            | Type    | Required | Description                                         |
| -------------------- | ------- | -------- | --------------------------------------------------- |
| `avatar.avatar_id`   | integer | ✅        | Your photo avatar ID                                |
| `avatar.avatar_type` | integer | ✅        | **Must be `1`** for photo avatars                   |
| `voice.type`         | string  | ✅        | "script" for text-to-speech                         |
| `voice.voice_id`     | string  | ✅        | Voice ID for text-to-speech                         |
| `voice.script`       | string  | ✅        | Text for avatar to speak                            |
| `aspect_ratio`       | string  | ✅        | portrait/landscape/square                           |
| `screen_style`       | integer | ✅        | 1=Full screen, 2=Split screen, 3=Picture in picture |

<Warning>
  **Important:** Set `avatar.avatar_type: 1` to use photo avatars. Using `0` will use public avatars instead.
</Warning>

***

## Code Examples

### Step 1: Create Video with Photo Avatar

Get your photo avatar ID first:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/avatars/photo_avatars' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "avatars": [
      {
        "id": 123,
        "name": "My Custom Avatar",
        "status": 1,
        "cover_url": "https://res.jogg.ai/avatars/cover_123.jpg"
      }
    ]
  }
}
```

Then create video with the photo avatar:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_from_avatar' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "avatar": {
      "avatar_id": 123,
      "avatar_type": 1
    },
    "voice": {
      "type": "script",
      "voice_id": "en-US-ChristopherNeural",
      "script": "Hello! This is my custom photo avatar speaking."
    },
    "aspect_ratio": "portrait",
    "screen_style": 1,
    "caption": true
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456"
  }
}
```

<Check>
  Ensure photo avatar `status` is `1` (completed) before creating videos. Status `0` means still processing.
</Check>

### Step 2: Check Video Status

Poll to check if video is ready:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/avatar_video/video_123456' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response (Processing):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456",
    "status": "processing",
    "created_at": 1732806631
  }
}
```

**Response (Completed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456",
    "status": "completed",
    "video_url": "https://res.jogg.ai/videos/video_123456.mp4",
    "cover_url": "https://res.jogg.ai/covers/cover_123456.jpg",
    "created_at": 1732806631
  }
}
```

<Tip>
  Instead of polling, use \[Webhooks]\(/api-reference/v2/API Documentation/WebhookIntegration) to get notified instantly when videos are ready!
</Tip>

***

## Use Case Examples

<AccordionGroup>
  <Accordion title="Personal Branding">
    Use your own face in videos:

    * Create photo avatar from your photo
    * Generate branded video content
    * Consistent personal presence across platforms
    * Scale your personal brand without being on camera
  </Accordion>

  <Accordion title="Company Spokesperson">
    Feature company executives or talent:

    * Create avatar from CEO or spokesperson photo
    * Generate company announcements and updates
    * Consistent company voice and appearance
    * Reduce production time and costs
  </Accordion>

  <Accordion title="Multi-Language Content">
    Speak in languages you don't know:

    * Create avatar from your photo once
    * Generate videos in 40+ languages
    * Maintain your face across all languages
    * Reach global audiences authentically
  </Accordion>

  <Accordion title="Influencer Content">
    Scale your content creation:

    * Use your photo avatar for multiple videos
    * Create content in different languages
    * Maintain your personal brand
    * Save time on video production
  </Accordion>
</AccordionGroup>

***

## Tips for Best Results

<Tip>
  **Photo Avatar Quality:**

  * Use high-quality source photos (1920x1080 or higher)
  * Ensure good lighting in source photo
  * Face should be clearly visible
  * Check avatar status is `1` (completed) before use
  * Test with short script first
</Tip>

**Script Recommendations:**

* Keep scripts natural and conversational
* Avoid very long scripts (\< 2 minutes)
* Test pronunciation of special terms
* Use appropriate voice for avatar personality

## Related Documentation

<CardGroup>
  <Card title="Create Photo Avatar" icon="camera" href="/api-reference/v2/API Documentation/CreatePhotoAvatar">
    Generate photo avatars from your photos
  </Card>

  <Card title="Get Photo Avatars" icon="users" href="/api-reference/v2/Avatar/PhotoAvatarsGet">
    List your photo avatars
  </Card>

  <Card title="Get Avatar Video" icon="video" href="/api-reference/v2/Video/AvatarVideoGet">
    Check video generation status
  </Card>

  <Card title="Get Voices" icon="microphone" href="/api-reference/v2/Voice/GetVoices">
    Browse available voices
  </Card>
</CardGroup>


# Create Talking Avatar Videos
Source: https://docs.jogg.ai/api-reference/v2/API Documentation/CreateAvatarVideos

Generate professional videos with realistic AI avatars speaking your script

## Introduction

Create engaging talking avatar videos with the JoggAI API. Select from 300+ realistic avatars, provide your script or audio, and generate professional videos in minutes.

### Key Features

<CardGroup>
  <Card title="300+ Avatars" icon="user">
    Professional avatars across all demographics
  </Card>

  <Card title="40+ Languages" icon="language">
    Natural text-to-speech in multiple languages
  </Card>

  <Card title="Fast Generation" icon="bolt">
    Videos ready in 2-5 minutes
  </Card>

  <Card title="Custom Options" icon="sliders">
    Control background, aspect ratio, and captions
  </Card>
</CardGroup>

### Workflow Overview

Avatar video creation is an **asynchronous 4-step process**:

<Steps>
  <Step title="Get Resources">
    Retrieve available avatars and voices from the API
  </Step>

  <Step title="Submit Video Request">
    Call create endpoint with avatar, voice, and script/audio
  </Step>

  <Step title="Background Processing">
    Video renders automatically (2-5 minutes)
  </Step>

  <Step title="Retrieve Result">
    Get video URL via webhook or polling
  </Step>
</Steps>

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant API
    participant Queue
    
    Note over Client: 1. Get Resources
    Client->>API: GET /avatars/public
    API-->>Client: Avatar list
    Client->>API: GET /voices
    API-->>Client: Voice list
    
    Note over Client,Queue: 2. Submit Request
    Client->>API: POST /create_video_from_avatar
    API->>Queue: Queue rendering task
    API-->>Client: 200 OK {video_id}
    
    Note over Queue: 3. Processing (2-5 min)
    Queue->>Queue: Generate video
    
    Note over Client,Queue: 4. Get Result
    alt Webhook (推荐)
        Queue->>Client: POST /webhook {video_url}
    else Polling
        Client->>API: GET /avatar_video/{id}
        API-->>Client: {video_url, status}
    end
```

<Info>
  This is an asynchronous process. Don't wait for the response - use webhooks or polling to get results.
</Info>

***

## Quick Start

### Related API Endpoints

| Endpoint                         | Purpose                | Documentation                                                  |
| -------------------------------- | ---------------------- | -------------------------------------------------------------- |
| `GET /avatars/public`            | Get public avatar list | [API Reference](/api-reference/v2/Avatar/PublicAvatarsGet)     |
| `GET /voices`                    | Get voice list         | [API Reference](/api-reference/v2/Voice/GetVoices)             |
| `POST /create_video_from_avatar` | Create avatar video    | [API Reference](/api-reference/v2/Video/CreateVideoFromAvatar) |
| `GET /avatar_video/{id}`         | Check video status     | [API Reference](/api-reference/v2/Video/AvatarVideoGet)        |

### Key Parameters

| Parameter            | Type    | Required | Description                                         |
| -------------------- | ------- | -------- | --------------------------------------------------- |
| `avatar`             | object  | ✅        | Avatar configuration                                |
| `avatar.avatar_id`   | integer | ✅        | Avatar ID from avatar list                          |
| `avatar.avatar_type` | integer | ✅        | 0=Public, 1=Custom avatar                           |
| `voice`              | object  | ✅        | Voice configuration                                 |
| `voice.type`         | string  | ✅        | "script" or "audio"                                 |
| `voice.voice_id`     | string  | ✅        | Voice ID for text-to-speech                         |
| `voice.script`       | string  | \*       | Text to speak (required when type is "script")      |
| `voice.audio_url`    | string  | \*       | Audio file URL (required when type is "audio")      |
| `aspect_ratio`       | string  | ✅        | portrait/landscape/square                           |
| `screen_style`       | integer | ✅        | 1=Full screen, 2=Split screen, 3=Picture in picture |
| `caption`            | boolean | ❌        | Enable subtitles (default: false)                   |

<Warning>
  You must provide either `voice.script` (for text-to-speech) OR `voice.audio_url` (for custom audio), but not both. Set `voice.type` to "script" or "audio" accordingly.
</Warning>

***

## Code Examples

### Step 1: Basic Avatar Video with Script

Create a simple video with text-to-speech:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_from_avatar' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "avatar": {
      "avatar_id": 81,
      "avatar_type": 0
    },
    "voice": {
      "type": "script",
      "voice_id": "en-US-ChristopherNeural",
      "script": "Welcome to JoggAI! Create amazing videos with AI avatars in minutes."
    },
    "aspect_ratio": "portrait",
    "screen_style": 1,
    "caption": true
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456"
  }
}
```

<Check>
  Save the `video_id` to check status later!
</Check>

### Step 2: Check Video Status

Poll to check if video is ready:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/avatar_video/video_123456' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response (Processing):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456",
    "status": "processing",
    "created_at": 1732806631
  }
}
```

**Response (Completed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456",
    "status": "completed",
    "video_url": "https://res.jogg.ai/videos/video_123456.mp4",
    "cover_url": "https://res.jogg.ai/covers/cover_123456.jpg",
    "created_at": 1732806631
  }
}
```

<Tip>
  Instead of polling, use \[Webhooks]\(/api-reference/v2/API Documentation/WebhookIntegration) to get notified instantly when videos are ready!
</Tip>

***

## Use Case Examples

<AccordionGroup>
  <Accordion title="Marketing & Social Media">
    Create engaging marketing videos for social platforms:

    * Use `aspect_ratio: "portrait"` for Instagram Stories/TikTok
    * Use `aspect_ratio: "landscape"` for YouTube
    * Enable `caption: true` for silent autoplay
  </Accordion>

  <Accordion title="E-Learning & Training">
    Generate educational content with AI presenters:

    * Choose professional avatars for credibility
    * Use clear, structured scripts
    * Add captions for accessibility
  </Accordion>

  <Accordion title="Product Demos">
    Showcase products with avatar presenters:

    * Use custom audio for brand voice
    * Combine with product visuals
    * Generate videos in multiple languages
  </Accordion>

  <Accordion title="Customer Support">
    Create FAQ and tutorial videos:

    * Batch generate common questions
    * Update easily by regenerating
    * Personalize with voice selection
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Avatar List API" icon="users" href="/api-reference/v2/Avatar/PublicAvatarsGet">
    Browse available avatars
  </Card>

  <Card title="Voice List API" icon="microphone" href="/api-reference/v2/Voice/GetVoices">
    Explore voice options
  </Card>

  <Card title="Upload Audio" icon="upload" href="/api-reference/v2/Asset/UploadAsset">
    Upload custom audio files
  </Card>

  <Card title="Webhook Setup" icon="webhook" href="/api-reference/v2/API Documentation/WebhookIntegration">
    Get instant notifications
  </Card>
</CardGroup>


# Create Photo Avatar
Source: https://docs.jogg.ai/api-reference/v2/API Documentation/CreatePhotoAvatar

Generate custom AI avatars from portrait photos

## Introduction

Transform portrait photos into talking AI avatars that can speak any script in 40+ languages. Create personalized avatars for branding, marketing, or custom content production. Photo avatars allow you to use your own face or team members' faces in videos, maintaining brand consistency across all content.

<video />

### Key Features

<CardGroup>
  <Card title="Personal Branding" icon="user-tie">
    Your face, your voice, your brand
  </Card>

  <Card title="Multilingual" icon="globe">
    One photo avatar speaks 40+ languages
  </Card>

  <Card title="Realistic Motion" icon="video">
    Natural facial expressions and movements
  </Card>

  <Card title="Fast Generation" icon="bolt">
    2-5 minutes to create custom avatar
  </Card>
</CardGroup>

### Workflow Overview

Photo avatar creation follows these steps:

<Steps>
  <Step title="Generate Avatar">
    Upload portrait photo → AI generates avatar (2-5 min)
  </Step>

  <Step title="Check Status">
    Poll for completion or use webhooks
  </Step>

  <Step title="Use in Videos">
    Create videos using your custom avatar
  </Step>

  <Step title="Add Motion (Optional)">
    Enhance avatar with realistic movements (2-3 min)
  </Step>
</Steps>

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant API
    participant Queue
    participant Webhook as Your Server (Optional)
    
    Note over Client,Webhook: Setup Webhook (Optional - One Time)
    Client->>API: POST /v2/endpoint
    API-->>Client: {endpoint_id, secret}
    
    Note over Client: Step 1: Generate Avatar
    Client->>API: POST /v2/photo_avatar/photo/generate
    API->>Queue: Queue generation
    API-->>Client: 200 OK {photo_id}
    
    Note over Queue: Processing (2-5 min)
    Queue->>Queue: Generate avatar
    
    alt Webhook Mode
        Note over Queue,Webhook: Step 2a: Webhook Notification
        Queue->>API: Generation complete
        API->>Webhook: POST webhook (generated_image_success)
        Webhook-->>API: 200 OK
    else Polling Mode
        Note over Client,Queue: Step 2b: Poll Status
        Client->>API: GET /v2/photo_avatar/photo?photo_id={id}
        API-->>Client: {status, image_url_list}
    end
    
    Note over Client: Step 3: Use in Videos
    Client->>API: POST /v2/create_video_from_avatar
    API-->>Client: {video_id}
    
    Note over Client,Queue: Step 4: Add Motion (Optional)
    Client->>API: POST /v2/photo_avatar/add_motion
    API->>Queue: Queue motion generation
    API-->>Client: 200 OK {motion_id}
    
    Note over Queue: Processing (2-3 min)
    Queue->>Queue: Generate motion
    
    alt Webhook Mode
        Note over Queue,Webhook: Step 5a: Motion Webhook Notification
        Queue->>API: Motion complete
        API->>Webhook: POST webhook (generated_motion_success)
        Webhook-->>API: 200 OK
    else Polling Mode
        Note over Client,Queue: Step 5b: Poll Motion Status
        Client->>API: GET /v2/photo_avatar?motion_id={id}
        API-->>Client: {status, motion_preview_url}
    end
```

<Info>
  **Optional Step:** Add motion for enhanced realism (additional 2-3 minutes). See [Step 4: Add Motion to Avatar](#step-4-add-motion-to-avatar-optional) section below.
</Info>

***

## Quick Start

### Related API Endpoints

| Endpoint                                   | Purpose                 | Documentation                                                  |
| ------------------------------------------ | ----------------------- | -------------------------------------------------------------- |
| `POST /v2/photo_avatar/photo/generate`     | Generate photo avatar   | [API Reference](/api-reference/v2/Avatar/PhotoAvatarGenerate)  |
| `GET /v2/photo_avatar/photo?photo_id={id}` | Check generation status | [API Reference](/api-reference/v2/Avatar/PhotoAvatarStatusGet) |
| `GET /v2/avatars/photo_avatars`            | List your photo avatars | [API Reference](/api-reference/v2/Avatar/PhotoAvatarsGet)      |
| `POST /v2/photo_avatar/add_motion`         | Add motion to avatar    | [API Reference](/api-reference/v2/Avatar/PhotoAvatarMotionAdd) |
| `GET /v2/photo_avatar?motion_id={id}`      | Check motion status     | [API Reference](/api-reference/v2/Avatar/MotionStatusCheck)    |

### Key Parameters

| Parameter      | Type   | Required | Description                                                                                                                |
| -------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `age`          | string | ✅        | Avatar age group: "Teenager", "Young adult", "Adult", "Elderly"                                                            |
| `avatar_style` | string | ✅        | Style category: "Professional", "Social"                                                                                   |
| `gender`       | string | ✅        | Avatar gender: "Female", "Male"                                                                                            |
| `model`        | string | ✅        | Photo generation model: "classic", "modern"                                                                                |
| `aspect_ratio` | string | ✅        | Photo aspect ratio: "portrait", "landscape", "square"                                                                      |
| `image_url`    | string | ❌        | Reference image URL (your portrait photo)                                                                                  |
| `ethnicity`    | string | ❌        | Avatar ethnicity: "European", "African", "South Asian", "East Asian", "Middle Eastern", "South American", "North American" |
| `background`   | string | ❌        | Background description                                                                                                     |
| `appearance`   | string | ❌        | Appearance description                                                                                                     |

<Warning>
  **Photo Requirements:** Use high-quality portrait photos (min 512x512px, recommended 1024x1024px). Face should be frontal, well-lit, and unobstructed. See [Photo Requirements](#photo-requirements) section for details.
</Warning>

***

## Code Examples

### Scenario 1: Basic Photo Avatar Creation

Create and use a photo avatar in videos:

#### Step 1: Generate Photo Avatar

Generate a custom avatar from your portrait photo:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/photo_avatar/photo/generate' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "age": "Adult",
    "avatar_style": "Professional",
    "gender": "Male",
    "model": "modern",
    "aspect_ratio": "portrait",
    "image_url": "https://example.com/portrait.jpg"
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "photo_id": "photo_abc123"
  }
}
```

<Check>
  Save the `photo_id` to check generation status!
</Check>

***

#### Step 2: Check Generation Status

Check if avatar generation is complete:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/photo_avatar/photo?photo_id=photo_abc123' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response (Processing):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "photo_id": "photo_abc123",
    "status": "in_progress"
  }
}
```

**Response (Completed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "photo_id": "photo_abc123",
    "status": "success",
    "image_url_list": [
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/bbb42ee5-8fa1-45b6-be47-105f97d2ca20.png",
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/7406e9b3-f1a7-4bae-9bb8-efed69b52bf4.png",
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/fd6a5880-9108-48d4-b501-afccec708378.png",
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/711bb2f6-ac1c-46bc-94c3-c0ce3a76cef9.png"
    ],
    "image_key_list": [
      "joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/bbb42ee5-8fa1-45b6-be47-105f97d2ca20.png",
      "joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/7406e9b3-f1a7-4bae-9bb8-efed69b52bf4.png",
      "joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/fd6a5880-9108-48d4-b501-afccec708378.png",
      "joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/711bb2f6-ac1c-46bc-94c3-c0ce3a76cef9.png"
    ]
  }
}
```

<Tip>
  Avatar generation typically takes 2-5 minutes. Use [Webhooks](/api-reference/v2/API%20Documentation/WebhookIntegration) for instant notifications instead of polling. See [Webhook Mode](#webhook-mode) section below for complete setup.
</Tip>

<Info>
  **Image Generation Charges:**

  * Each call generates four images
  * Each image deducts 0.05 credit
  * Four images deduct a total of 0.2 credit
</Info>

<Check>
  We have generated our AI Avatar photos. Now we can use these `image_key` values to create new looks or use the avatar in videos.
</Check>

***

#### Step 3: Create Video with Photo Avatar

Create a video using your photo avatar:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_from_avatar' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "avatar": {
      "avatar_id": 123,
      "avatar_type": 1
    },
    "voice": {
      "type": "script",
      "voice_id": "en-US-ChristopherNeural",
      "script": "Hello! I am your custom photo avatar."
    },
    "aspect_ratio": "portrait",
    "screen_style": 1,
    "caption": true
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456"
  }
}
```

<Warning>
  **Important:** Always use `avatar_type: 1` for photo avatars (custom avatars). Use `avatar_type: 0` for public avatars.
</Warning>

***

### Webhook Mode

Use webhooks to receive instant notifications when avatar generation completes, eliminating the need for polling.

#### Step 1: Setup Webhook Endpoint

First, create a webhook endpoint to receive notifications:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/endpoint' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://your-domain.com/webhook",
    "events": [
      "generated_image_success",
      "generated_image_failed",
      "generated_motion_success",
      "generated_motion_failed"
    ],
    "status": "enabled"
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "endpoint_id": "wh_123456789",
    "url": "https://your-domain.com/webhook",
    "secret": "whsec_abc123xyz",
    "status": "enabled",
    "events": [
      "generated_image_success",
      "generated_image_failed",
      "generated_motion_success",
      "generated_motion_failed"
    ],
    "username": "johndoe",
    "created_at": 1732806631
  }
}
```

<Check>
  Save the `secret` - you'll need it to verify webhook signatures!
</Check>

#### Step 2: Generate Photo Avatar

Generate avatar as usual:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/photo_avatar/photo/generate' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "age": "Adult",
    "avatar_style": "Professional",
    "gender": "Male",
    "model": "modern",
    "aspect_ratio": "portrait",
    "image_url": "https://example.com/portrait.jpg"
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "photo_id": "photo_abc123"
  }
}
```

#### Step 3: Receive Webhook Notification

When generation completes (2-5 minutes), your webhook endpoint will receive a POST request:

**Success Event Payload:**

```json theme={null}
{
  "event": "generated_image_success",
  "timestamp": 1732806631,
  "data": {
    "photo_id": "photo_abc123",
    "photo_urls": [
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/bbb42ee5-8fa1-45b6-be47-105f97d2ca20.png",
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/7406e9b3-f1a7-4bae-9bb8-efed69b52bf4.png",
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/fd6a5880-9108-48d4-b501-afccec708378.png",
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/711bb2f6-ac1c-46bc-94c3-c0ce3a76cef9.png"
    ]
  }
}
```

**Failed Event Payload:**

```json theme={null}
{
  "event": "generated_image_failed",
  "timestamp": 1732806631,
  "data": {
    "photo_id": "photo_abc123",
    "error": "Image generation failed due to invalid parameters"
  }
}
```

#### Step 4: Verify Webhook Signature

Always verify webhook signatures to ensure requests come from JoggAI:

**Example (Node.js):**

```javascript theme={null}
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  
  if (!verifyWebhookSignature(req.body, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(req.body);
  
  if (event.event === 'generated_image_success') {
    // Handle success
    const { photo_id, photo_urls } = event.data;
    console.log(`Avatar ${photo_id} generated successfully!`);
    // Process photo_urls...
  } else if (event.event === 'generated_image_failed') {
    // Handle failure
    const { photo_id, error } = event.data;
    console.error(`Avatar ${photo_id} failed: ${error}`);
  }
  
  res.status(200).send('OK');
});
```

#### Step 5: Motion Generation with Webhooks

When adding motion, you'll receive notifications for motion generation:

**Motion Success Event:**

```json theme={null}
{
  "event": "generated_motion_success",
  "timestamp": 1732806631,
  "data": {
    "motion_id": "motion_xyz789",
    "motion_url": "https://files2.jogg.ai/avatar/v3/motion_xyz789/full/2.0/preview_video_target.mp4",
    "photo_url": "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/bbb42ee5-8fa1-45b6-be47-105f97d2ca20.png"
  }
}
```

**Motion Failed Event:**

```json theme={null}
{
  "event": "generated_motion_failed",
  "timestamp": 1732806631,
  "data": {
    "motion_id": "motion_xyz789",
    "error": "Motion generation failed due to processing error"
  }
}
```

<Info>
  **Webhook Events for Photo Avatar:**

  * `generated_image_success` - Triggered when image generation completes successfully
  * `generated_image_failed` - Triggered when image generation fails
  * `generated_motion_success` - Triggered when motion generation completes successfully
  * `generated_motion_failed` - Triggered when motion generation fails

  See [Webhook Integration Guide](/api-reference/v2/API%20Documentation/WebhookIntegration) for complete webhook documentation.
</Info>

***

### Scenario 2: Photo Avatar with Motion Enhancement

Create a photo avatar with enhanced motion for more realistic videos:

#### Step 1: Generate Photo Avatar

Generate a custom avatar from your portrait photo:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/photo_avatar/photo/generate' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "age": "Adult",
    "avatar_style": "Professional",
    "gender": "Male",
    "model": "modern",
    "aspect_ratio": "portrait",
    "image_url": "https://example.com/portrait.jpg"
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "photo_id": "photo_abc123"
  }
}
```

***

#### Step 2: Check Generation Status

Check if avatar generation is complete:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/photo_avatar/photo?photo_id=photo_abc123' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response (Completed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "photo_id": "photo_abc123",
    "status": "success",
    "image_url_list": [
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/bbb42ee5-8fa1-45b6-be47-105f97d2ca20.png",
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/7406e9b3-f1a7-4bae-9bb8-efed69b52bf4.png",
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/fd6a5880-9108-48d4-b501-afccec708378.png",
      "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/711bb2f6-ac1c-46bc-94c3-c0ce3a76cef9.png"
    ],
    "image_key_list": [
      "joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/bbb42ee5-8fa1-45b6-be47-105f97d2ca20.png",
      "joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/7406e9b3-f1a7-4bae-9bb8-efed69b52bf4.png",
      "joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/fd6a5880-9108-48d4-b501-afccec708378.png",
      "joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/711bb2f6-ac1c-46bc-94c3-c0ce3a76cef9.png"
    ]
  }
}
```

***

#### Step 3: Add Motion to Avatar

Enhance avatar with realistic movements:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/photo_avatar/add_motion' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "photo_id": "photo_abc123",
    "image_url": "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/bbb42ee5-8fa1-45b6-be47-105f97d2ca20.png",
    "name": "My Photo Avatar",
    "voice_id": "en-US-ChristopherNeural",
    "model": "2.0",
    "description": "Professional avatar for marketing videos"
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "avatar_id": 123,
    "motion_id": "motion_xyz789",
    "status": "processing"
  }
}
```

<Check>
  Save the `motion_id` and `avatar_id` to check motion generation status!
</Check>

***

#### Step 4: Check Motion Status

Check if motion generation is complete:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/photo_avatar?motion_id=motion_xyz789' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response (Processing):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "motion_id": "motion_xyz789",
    "avatar_id": 123,
    "image_url": "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/bbb42ee5-8fa1-45b6-be47-105f97d2ca20.png",
    "name": "My Photo Avatar",
    "status": "processing",
    "motion_preview_url": "",
    "voice_id": "en-US-ChristopherNeural"
  }
}
```

**Response (Completed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "motion_id": "motion_xyz789",
    "avatar_id": 123,
    "image_url": "https://res.jogg.ai/joggUserData/aigc/photo/25-1a0ab69d92b6449796d6e9ec0b993a3f/bbb42ee5-8fa1-45b6-be47-105f97d2ca20.png",
    "name": "My Photo Avatar",
    "status": "completed",
    "motion_preview_url": "https://files2.jogg.ai/avatar/v3/motion_xyz789/full/2.0/preview_video_target.mp4",
    "voice_id": "en-US-ChristopherNeural"
  }
}
```

<Tip>
  Motion generation adds 2-3 minutes but significantly improves avatar realism and natural movement.
</Tip>

<Info>
  **Motion Generation Charges:**

  * Motion 1.0 deducts 2 credits
  * Motion 2.0 deducts 2 credits
  * Motion 2.0 Pro deducts 3 credits
  * Motion 3.0 deducts 2 credits
</Info>

***

#### Step 5: Create Video with Enhanced Avatar

Create a video using your photo avatar with motion:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_from_avatar' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "avatar": {
      "avatar_id": 123,
      "avatar_type": 1
    },
    "voice": {
      "type": "script",
      "voice_id": "en-US-ChristopherNeural",
      "script": "Hello! I am your custom photo avatar with enhanced motion."
    },
    "aspect_ratio": "portrait",
    "screen_style": 1,
    "caption": true
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456"
  }
}
```

<Warning>
  **Important:** Always use `avatar_type: 1` for photo avatars (custom avatars). Use `avatar_type: 0` for public avatars.
</Warning>

***

## Advanced Examples

### Scenario 1: List Your Photo Avatars

Get all your photo avatars:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/avatars/photo_avatars' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "avatars": [
      {
        "id": 123,
        "name": "My Photo Avatar",
        "cover_url": "https://res.jogg.ai/avatars/cover_123.jpg",
        "status": 1,
        "fail_msg": ""
      }
    ]
  }
}
```

<Info>
  Status values: `0` = Processing, `1` = Completed, `2` = Failed. Save the `id` (integer) to use in video creation.
</Info>

***

## Photo Requirements

### Image Specifications

| Requirement      | Specification                            |
| ---------------- | ---------------------------------------- |
| **Format**       | JPG, PNG, WebP                           |
| **File Size**    | Maximum 10MB                             |
| **Resolution**   | Min: 512x512px, Recommended: 1024x1024px |
| **Aspect Ratio** | Square or portrait                       |
| **Face**         | Clear, frontal, well-lit, unobstructed   |

### Photo Quality Guidelines

<AccordionGroup>
  <Accordion title="✅ Good Photos">
    **What works best:**

    * Face directly facing camera (frontal view)
    * Even, soft lighting (no harsh shadows)
    * Clear facial features (high resolution)
    * Neutral or slight smile expression
    * Plain, solid-color background
    * Natural makeup and appearance
    * No glasses (or non-reflective if needed)
    * Hair not covering face
  </Accordion>

  <Accordion title="❌ Avoid These">
    **What doesn't work:**

    * Side profile or angled face
    * Poor lighting or harsh shadows
    * Blurry or low-resolution images
    * Face obstructed (hands, objects, masks)
    * Busy or cluttered backgrounds
    * Sunglasses or reflective glasses
    * Hats or head coverings
    * Extreme expressions (laughing, frowning)
    * Heavy filters or editing
  </Accordion>

  <Accordion title="Lighting Tips">
    **Best lighting setup:**

    * Natural outdoor light (overcast day is ideal)
    * Soft indoor lighting (no overhead harsh lights)
    * Face evenly lit (no one-sided shadows)
    * Avoid backlit photos (light behind subject)
    * Use diffused light when possible
    * Golden hour for outdoor photos
  </Accordion>

  <Accordion title="Background Recommendations">
    **Background best practices:**

    * Plain, solid color works best
    * White, gray, or neutral tones
    * Good contrast with subject
    * No distracting elements
    * Avoid patterns or textures
    * Professional backdrop preferred
  </Accordion>
</AccordionGroup>

***

## Use Case Examples

<AccordionGroup>
  <Accordion title="Personal Branding">
    Create your digital spokesperson:

    * **Social Media**: Personalized video messages at scale
    * **Email Marketing**: Custom video intros
    * **Online Courses**: Instructor presence without recording
    * **Thought Leadership**: Consistent personal brand across content
  </Accordion>

  <Accordion title="Company Spokesperson">
    Feature executives or team members:

    * **Announcements**: CEO messages in multiple languages
    * **Product Demos**: Consistent company voice
    * **Training Videos**: Scale expert knowledge
    * **Customer Support**: Personalized video responses
  </Accordion>

  <Accordion title="Multilingual Content">
    One photo, many languages:

    * Create avatar once from photo
    * Generate videos in 40+ languages
    * Maintain same face across all markets
    * No need for multiple recordings
  </Accordion>
</AccordionGroup>

***

## Tips for Best Results

<Tip>
  **Photo Preparation:**

  * Use professional headshots or high-quality smartphone photos
  * Studio or natural outdoor lighting works best
  * Sharp focus, no blur
  * No filters or heavy editing
  * Natural skin tones
</Tip>

**Testing Strategy:**

* Test with one photo first
* Generate video with short script
* Verify avatar quality and movements
* Test different voices and languages
* Adjust source photo if needed

**Organization:**

* Use descriptive names for avatars
* Document avatar IDs for easy reference
* Note which photos work best
* Maintain source photo library
* Track motion settings used

**Avatar Type Reference:**

| Type              | Value | Description              | Use Case                 |
| ----------------- | ----- | ------------------------ | ------------------------ |
| **Public Avatar** | `0`   | Pre-made library avatars | Quick, generic content   |
| **Custom Avatar** | `1`   | Photo avatars            | Personal/branded content |

<Check>
  Always use `avatar_type: 1` when creating videos with photo avatars.
</Check>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Photo Quality Too Low">
    **Error:** `Photo quality insufficient`

    **Solutions:**

    * Use minimum 512x512px resolution (1024x1024px recommended)
    * Ensure image is sharp, not blurry
    * Use well-lit photo
    * Avoid heavily compressed images
    * Try professional headshot
  </Accordion>

  <Accordion title="Face Not Detected">
    **Error:** `No face detected in photo`

    **Solutions:**

    * Ensure face is clearly visible and frontal
    * Remove obstructions (hands, masks, hair)
    * Face should not be profile or angled
    * Check lighting and contrast
    * Ensure face occupies enough of frame
  </Accordion>

  <Accordion title="Generation Failed">
    **Error:** `Avatar generation failed`

    **Solutions:**

    * Try a different photo
    * Verify photo meets all requirements
    * Ensure photo URL is publicly accessible
    * Check file format is supported (JPG/PNG/WebP)
    * Verify file size is under 10MB
    * Retry the generation
  </Accordion>

  <Accordion title="Avatar Looks Unnatural">
    **Issue:** Generated avatar doesn't look realistic

    **Solutions:**

    * Use higher quality source photo
    * Ensure proper, even lighting
    * Use photo with neutral expression
    * Plain background helps AI focus on face
    * Consider professional headshot
    * Test with different photos
  </Accordion>

  <Accordion title="Motion Not Working">
    **Issue:** Motion generation fails or looks wrong

    **Solutions:**

    * Ensure base avatar generation completed first
    * Check avatar status is "completed" (status = 1)
    * Verify avatar quality is good
    * Try different `motion_type`
    * Re-generate avatar with better photo
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Avatar Videos with Photo Avatar" icon="video" href="/api-reference/v2/API Documentation/AvatarVideosWithPhotoAvatar">
    Using photo avatars in videos
  </Card>

  <Card title="Create Avatar Videos" icon="user" href="/api-reference/v2/API Documentation/CreateAvatarVideos">
    Main avatar video guide
  </Card>

  <Card title="Upload Media" icon="upload" href="/api-reference/v2/API Documentation/UploadMedia">
    How to upload photos and media
  </Card>

  <Card title="Generate Photo Avatar API" icon="camera" href="/api-reference/v2/Avatar/PhotoAvatarGenerate">
    Complete API reference
  </Card>

  <Card title="Webhook Integration" icon="webhook" href="/api-reference/v2/API%20Documentation/WebhookIntegration">
    Complete webhook setup guide
  </Card>
</CardGroup>


# Create Video from Template
Source: https://docs.jogg.ai/api-reference/v2/API Documentation/CreateVideoFromTemplate

Generate professional videos quickly using pre-designed templates

## Introduction

Use templates to create professional videos with consistent branding. Choose from JoggAI's template library or create custom templates with your own layout and design. Templates allow you to generate multiple videos quickly by simply changing variable values.

### Key Features

<CardGroup>
  <Card title="Fast Creation" icon="bolt">
    Skip the design process with ready-made templates
  </Card>

  <Card title="Brand Consistency" icon="palette">
    Maintain consistent style across all videos
  </Card>

  <Card title="Batch Processing" icon="layer-group">
    Generate multiple videos with the same template
  </Card>

  <Card title="Flexible Variables" icon="sliders">
    Customize text, images, videos, and scripts
  </Card>
</CardGroup>

### Workflow Overview

Template video creation is a **4-step process**:

<Steps>
  <Step title="Create Template (One-time)">
    Design your template in the dashboard and define variables
  </Step>

  <Step title="Select Template">
    Browse and choose a template from your library
  </Step>

  <Step title="Customize Variables">
    Provide values for template variables (text, images, etc.)
  </Step>

  <Step title="Generate & Retrieve">
    Video renders in background, retrieve when complete
  </Step>
</Steps>

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant API
    participant Queue
    
    Note over Client: Step 1: Select Template
    Client->>API: GET /templates/custom
    API-->>Client: Template list
    Client->>API: GET /template/custom/{id}
    API-->>Client: Template details + variables
    
    Note over Client,Queue: Step 2: Create Video
    Client->>API: POST /create_video_with_template
    API->>Queue: Queue rendering
    API-->>Client: 200 OK {video_id}
    
    Note over Queue: Step 3: Processing (2-5 min)
    Queue->>Queue: Generate video
    
    alt Webhook
        Queue->>Client: POST /webhook {video_url}
    else Polling
        Client->>API: GET /template_video/{video_id}
        API-->>Client: {video_url, status}
    end
```

<Info>
  Template videos typically take 2-5 minutes to generate. Use webhooks for best experience.
</Info>

***

## Creating Templates

Before using templates, you need to create your own templates. Templates allow you to define a fixed layout with replaceable variables for text, images, videos, scripts, and avatars.

### Step 1: Create Template in Dashboard

Create your own templates in the user interface. There are two types of templates: public library templates and custom templates created by you.

**To create a template:**

1. Log in to [app.jogg.ai](https://app.jogg.ai) and navigate to the Template Library section
2. Click "Create Template" and design your video layout
3. Once created, copy the `template_id` from the template card

<img alt="" />

<Info>
  Templates can be created in the dashboard interface. You can design the layout, animations, background music, and define variables for customization.
</Info>

### Step 2: Define Variables in Template

In the template editor, define variables for elements you want to make replaceable:

**Supported Variable Types:**

* **Text**: Static text elements (titles, descriptions, labels)
* **Image**: Image placeholders (product photos, logos, backgrounds)
* **Video**: Video placeholders (background videos, product demos)
* **Script**: Script content for text-to-speech (spoken content)
* **Avatar**: Avatar selection (can be overridden per video)

**How to Define Variables:**

In the template editor, you can customize variable names for elements in the template to facilitate identification and replacement. Currently, only `script content, text, image, video and avatar` are supported.

1. Select an element in your template (text, image, video, or script)
2. Click "Set as Variable" or "Define Variable"
3. Enter a variable name (e.g., `product_name`, `product_image`, `script_en`)
4. Set the variable type (text, image, video, script, or avatar)
5. Mark as required or optional

**Example: Defining Text Variables**

<img alt="" />

**Example: Defining Media Variables (Image/Video)**

<img alt="" />

**Example: Defining Script Variables**

<img alt="" />

<Tip>
  Use descriptive variable names that match your content structure. For example: `product_name`, `product_image`, `script_en`, `background_video`.
</Tip>

### Step 3: Get Template Details

After creating your template, you can view all defined variables in the template editor or get them via API. The template details will show all variables you've defined, including their names, types, and whether they're required.

<Check>
  All variables defined in your template will be listed with their names and types. Use these exact variable names when creating videos from the template.
</Check>

***

## Quick Start

### Related API Endpoints

| Endpoint                              | Purpose                    | Documentation                                                    |
| ------------------------------------- | -------------------------- | ---------------------------------------------------------------- |
| `GET /v2/templates/custom`            | List your custom templates | [API Reference](/api-reference/v2/Template/GetTemplates)         |
| `GET /v2/template/custom/{id}`        | Get template details       | [API Reference](/api-reference/v2/Template/GetTemplateById)      |
| `POST /v2/create_video_with_template` | Create video from template | [API Reference](/api-reference/v2/Video/CreateVideoWithTemplate) |
| `GET /v2/template_video/{video_id}`   | Check video status         | [API Reference](/api-reference/v2/Video/TemplateVideoGet)        |

### Key Parameters

| Parameter          | Type    | Required | Description                                         |
| ------------------ | ------- | -------- | --------------------------------------------------- |
| `template_id`      | integer | ✅        | Template ID from template list                      |
| `variables`        | array   | ✅        | Template variables array (see Variable Types below) |
| `avatar_id`        | integer | ❌        | Override template avatar                            |
| `avatar_type`      | integer | ❌        | 0=Public, 1=Custom                                  |
| `voice_language`   | string  | ✅        | Voice language for text-to-speech                   |
| `voice_id`         | string  | ❌        | Override template voice ID                          |
| `video_name`       | string  | ❌        | Custom name for the video                           |
| `captions_enabled` | boolean | ❌        | Enable subtitles (default: false)                   |
| `webhook_url`      | string  | ❌        | Webhook URL for status notifications                |

<Warning>
  **Variables Required:** All required variables from the template must be provided in the `variables` array. Get template details first to see required variables.
</Warning>

***

## Code Examples

### Step 1: Get Template List

Browse your custom templates:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/templates/custom?aspect_ratio=portrait' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "templates": [
      {
        "id": 1234,
        "name": "Product Showcase Template",
        "cover_url": "https://res.jogg.ai/templates/cover_1234.jpg",
        "preview_url": "https://res.jogg.ai/templates/preview_1234.mp4",
        "aspect_ratio": 0
      }
    ]
  }
}
```

<Check>
  Filter by `aspect_ratio`: `portrait` (Portrait), `landscape` (Landscape), `square` (Square)
</Check>

***

### Step 2: Get Template Details

View template variables and requirements:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/template/custom/1234' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "id": 1234,
    "name": "Product Showcase Template",
    "aspect_ratio": 0,
    "variables": [
      {
        "name": "product_name",
        "type": "text",
        "required": true
      },
      {
        "name": "product_image",
        "type": "image",
        "required": true
      },
      {
        "name": "script",
        "type": "script",
        "required": true
      }
    ]
  }
}
```

<Tip>
  Check the `variables` array to see what values you need to provide. Required variables must be included in your request.
</Tip>

***

### Step 3: Create Video with Template

**Basic Example: Text Variables**

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_with_template' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "template_id": 1234,
    "voice_language": "english",
    "voice_id": "en-US-ChristopherNeural",
    "avatar_id": 81,
    "avatar_type": 0,
    "captions_enabled": true,
    "variables": [
      {
        "type": "text",
        "name": "product_name",
        "properties": {
          "content": "Amazing Smart Watch"
        }
      },
      {
        "type": "script",
        "name": "script",
        "properties": {
          "content": "Discover the future of wearable technology with our Amazing Smart Watch!"
        }
      }
    ]
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456"
  }
}
```

<Check>
  Save the `video_id` to check status later!
</Check>

***

### Step 4: Check Video Status

Poll to check if video is ready:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/template_video/video_123456' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response (Processing):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456",
    "status": "processing"
  }
}
```

**Response (Completed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456",
    "status": "completed",
    "video_url": "https://res.jogg.ai/videos/video_123456.mp4",
    "cover_url": "https://res.jogg.ai/covers/cover_123456.jpg",
    "duration": 30,
    "created_at": 1732806631
  }
}
```

<Tip>
  Instead of polling, use \[Webhooks]\(/api-reference/v2/API Documentation/WebhookIntegration) to get notified instantly when videos are ready!
</Tip>

***

## Advanced Examples

### Create Video with Image Variables

Include custom images in template:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_with_template' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "template_id": 1234,
    "voice_language": "english",
    "voice_id": "en-US-ChristopherNeural",
    "avatar_id": 81,
    "avatar_type": 0,
    "variables": [
      {
        "type": "text",
        "name": "product_name",
        "properties": {
          "content": "Amazing Smart Watch"
        }
      },
      {
        "type": "image",
        "name": "product_image",
        "properties": {
          "url": "https://example.com/watch.jpg"
        }
      },
      {
        "type": "script",
        "name": "script",
        "properties": {
          "content": "Check out this amazing smart watch!"
        }
      }
    ]
  }'
```

<Info>
  Use `url` for external images or `asset_id` for uploaded assets.
</Info>

***

### Create Video with Uploaded Assets

Use previously uploaded assets:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_with_template' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "template_id": 1234,
    "template_type": "user",
    "voice_language": "english",
    "variables": [
      {
        "type": "image",
        "name": "product_image",
        "properties": {
          "asset_id": 5678
        }
      },
      {
        "type": "video",
        "name": "background_video",
        "properties": {
          "asset_id": 9012
        }
      }
    ]
  }'
```

<Tip>
  Upload assets first using \[Upload Media]\(/api-reference/v2/API Documentation/UploadMedia), then reference by `asset_id`.
</Tip>

***

## Variable Types Reference

Templates support different variable types. Each variable must include `type`, `name`, and `properties`:

### Text Variables

```json theme={null}
{
  "type": "text",
  "name": "product_name",
  "properties": {
    "content": "Your text here"
  }
}
```

### Image Variables

Use external URL or uploaded asset:

```json theme={null}
{
  "type": "image",
  "name": "product_image",
  "properties": {
    "url": "https://example.com/image.jpg"
  }
}
```

OR

```json theme={null}
{
  "type": "image",
  "name": "product_image",
  "properties": {
    "asset_id": 1234
  }
}
```

### Video Variables

Use external URL or uploaded asset:

```json theme={null}
{
  "type": "video",
  "name": "background_video",
  "properties": {
    "url": "https://example.com/video.mp4"
  }
}
```

OR

```json theme={null}
{
  "type": "video",
  "name": "background_video",
  "properties": {
    "asset_id": 5678
  }
}
```

### Script Variables

```json theme={null}
{
  "type": "script",
  "name": "script",
  "properties": {
    "content": "Your script text here"
  }
}
```

***

## Use Case Examples

<AccordionGroup>
  <Accordion title="E-commerce Product Videos">
    Create consistent product videos at scale:

    * Use same template for entire catalog
    * Swap product images and names
    * Maintain brand consistency
    * Batch process hundreds of products
  </Accordion>

  <Accordion title="Social Media Campaigns">
    Launch coordinated campaigns:

    * Create template matching brand guidelines
    * Generate videos for different products
    * Consistent look across all posts
    * Quick turnaround for trending topics
  </Accordion>

  <Accordion title="Real Estate Listings">
    Showcase properties professionally:

    * Standard template for all listings
    * Swap property images and details
    * Include agent information
    * Generate videos for new listings instantly
  </Accordion>

  <Accordion title="Educational Content">
    Create course materials efficiently:

    * Consistent lesson format
    * Swap topics and examples
    * Professional appearance
    * Scale content production
  </Accordion>
</AccordionGroup>

***

## Tips for Best Results

<Tip>
  **Template Creation:**

  * Design templates with clear, consistent layouts
  * Use descriptive variable names (e.g., `product_name` not `var1`)
  * Define all elements you want to customize as variables
  * Test template with sample data before bulk production
  * Keep template design simple for faster rendering
  * Consider aspect ratio requirements (portrait, landscape, square)
</Tip>

<Tip>
  **Template Selection:**

  * Choose templates matching your aspect ratio needs (9:16, 16:9, 1:1)
  * Preview templates before bulk production
  * Test with sample data first
  * Ensure template variables match your data structure
</Tip>

**Image Quality:**

* Use high-resolution images (recommended 1920x1080 or higher)
* Ensure image URLs are publicly accessible (HTTPS)
* Test images are not corrupted
* Optimize image file sizes (maximum 10MB)

**Variable Configuration:**

* Get template details first to see all required variables
* Match variable names exactly as defined in the template
* Use correct variable types (text, image, video, script)
* Provide all required variables to avoid errors

**Batch Processing:**

* Submit all requests first
* Use \[Webhooks]\(/api-reference/v2/API Documentation/WebhookIntegration) for notifications
* Implement retry logic for failures
* Monitor rate limits

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Template Not Found">
    **Error**: `Template ID does not exist`

    **Solutions:**

    * Verify `template_id` is correct
    * Verify template\_id exists and is accessible
    * List all templates to find correct ID
    * Ensure template exists in your account
  </Accordion>

  <Accordion title="Missing Required Variables">
    **Error**: `Required template variable missing`

    **Solutions:**

    * Get template details to see required variables
    * Ensure all required variables are in `variables` array
    * Check variable names match exactly (case-sensitive)
    * Verify variable types are correct
  </Accordion>

  <Accordion title="Image/Video URL Not Accessible">
    **Error**: `Failed to load asset from URL`

    **Solutions:**

    * Ensure URLs are publicly accessible
    * Use HTTPS (not HTTP)
    * Check file format is supported
    * Verify file size is within limits
    * Test URL in browser first
  </Accordion>

  <Accordion title="Video Generation Failed">
    **Error**: Video status is "failed"

    **Solutions:**

    * Check error message in response
    * Verify all assets are valid
    * Ensure script length is appropriate
    * Try with simpler variables first
    * Contact support if issue persists
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Get Templates API" icon="layer-group" href="/api-reference/v2/Template/GetTemplates">
    Browse available templates
  </Card>

  <Card title="Get Template Details" icon="file-lines" href="/api-reference/v2/Template/GetTemplateById">
    View template variables
  </Card>

  <Card title="Upload Media" icon="upload" href="/api-reference/v2/API Documentation/UploadMedia">
    Upload images and videos for templates
  </Card>

  <Card title="Webhook Integration" icon="webhook" href="/api-reference/v2/API Documentation/WebhookIntegration">
    Get notified when videos are ready
  </Card>
</CardGroup>


# Check Video Result & Status
Source: https://docs.jogg.ai/api-reference/v2/API Documentation/GetResult

Retrieve video generation status and download URLs

## Introduction

Check the status of your video generation tasks and retrieve download URLs when completed. This guide covers polling strategies and status interpretation for all video types (Avatar Videos, Product Videos, and Template Videos). Use webhooks for instant notifications or polling for status checks.

### Key Features

<CardGroup>
  <Card title="Real-Time Status" icon="circle-check">
    Get current processing status instantly
  </Card>

  <Card title="Video Download" icon="download">
    Retrieve final video URLs when ready
  </Card>

  <Card title="Error Details" icon="circle-exclamation">
    Get detailed error messages if failed
  </Card>

  <Card title="Metadata" icon="info-circle">
    Access duration, cover images, and more
  </Card>
</CardGroup>

### Workflow Overview

Video generation follows a standard status flow:

```mermaid theme={null}
stateDiagram-v2
    [*] --> pending: Video Created
    pending --> processing: Rendering Started
    processing --> completed: Success
    processing --> failed: Error
    completed --> [*]
    failed --> [*]
    
    note right of processing
        Takes 2-10 minutes
        depending on video type
    end note
```

<Info>
  Videos typically take 2-10 minutes to generate depending on length and complexity. Use webhooks for instant notifications instead of polling.
</Info>

***

## Quick Start

### Related API Endpoints

| Video Type          | Get Status Endpoint                        | Documentation                                             |
| ------------------- | ------------------------------------------ | --------------------------------------------------------- |
| **Avatar Videos**   | `GET /v2/avatar_video/{id}`                | [API Reference](/api-reference/v2/Video/AvatarVideoGet)   |
| **Product Videos**  | `GET /v2/product_video/{product_video_id}` | [API Reference](/api-reference/v2/Video/ProductVideoGet)  |
| **Template Videos** | `GET /v2/template_video/{video_id}`        | [API Reference](/api-reference/v2/Video/TemplateVideoGet) |

### Status Values

| Status       | Description             | Next Action               |
| ------------ | ----------------------- | ------------------------- |
| `pending`    | Queued, not started yet | Wait and poll again       |
| `processing` | Currently rendering     | Wait and poll again       |
| `completed`  | Video is ready          | Download from `video_url` |
| `failed`     | Error occurred          | Check error message       |

<Tip>
  **Recommended**: Use \[Webhooks]\(/api-reference/v2/API Documentation/WebhookIntegration) instead of polling for better performance and instant notifications.
</Tip>

***

## Code Examples

### Scenario 1: Check Avatar Video Status

Poll for avatar video completion:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/avatar_video/video_123456' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response (Processing):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456",
    "status": "processing",
    "created_at": 1732806631
  }
}
```

**Response (Completed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456",
    "status": "completed",
    "video_url": "https://res.jogg.ai/videos/video_123456.mp4",
    "cover_url": "https://res.jogg.ai/covers/video_123456.jpg",
    "duration": 30,
    "created_at": 1732806631
  }
}
```

<Check>
  When `status` is `completed`, download the video from `video_url`.
</Check>

***

### Scenario 1: Check Product Video Status

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/product_video/pv_789012' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response (Completed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "id": "pv_789012",
    "status": "completed",
    "video_url": "https://res.jogg.ai/videos/pv_789012.mp4",
    "cover_url": "https://res.jogg.ai/covers/pv_789012.jpg",
    "video_duration": 30.5,
    "created_at": 1732806631
  }
}
```

**Response (Failed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "id": "pv_789012",
    "status": "failed",
    "error": {
      "code": 50000,
      "message": "Insufficient media quality for video generation"
    },
    "created_at": 1732806631
  }
}
```

<Warning>
  If status is `failed`, check the `error` object for details and retry with corrected parameters.
</Warning>

***

### Scenario 1: Check Template Video Status

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/template_video/video_123456' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response (Completed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_id": "video_123456",
    "status": "completed",
    "video_url": "https://res.jogg.ai/videos/video_123456.mp4",
    "cover_url": "https://res.jogg.ai/covers/cover_123456.jpg",
    "duration": 30,
    "created_at": 1732806631
  }
}
```

***

## Use Case Examples

<AccordionGroup>
  <Accordion title="Polling Strategy">
    **When to Use**: When webhooks are not available or you need immediate status checks.

    **Recommended Schedule**:

    * Wait 10-15 seconds before first poll
    * Poll every 10 seconds for first minute
    * Increase to 30 seconds, then 60 seconds
    * Stop after 10 minutes and check for issues

    <Warning>
      Do not poll faster than every 5 seconds to avoid rate limiting.
    </Warning>
  </Accordion>

  <Accordion title="Webhook Integration">
    **When to Use**: Recommended for production applications.

    **Advantages**:

    * ✅ No polling overhead
    * ✅ Instant notifications
    * ✅ Reduced API calls
    * ✅ Better scalability
    * ✅ Lower latency

    See \[Webhook Integration]\(/api-reference/v2/API Documentation/WebhookIntegration) for setup.
  </Accordion>

  <Accordion title="Batch Status Checks">
    **When to Use**: Checking status of multiple videos.

    **Strategy**:

    * Use list endpoints (`/v2/template_videos`, `/v2/product_videos`) to get status of multiple videos
    * Filter by status to find completed/failed videos
    * Process completed videos, retry failed ones
  </Accordion>
</AccordionGroup>

***

## Tips for Best Results

<Tip>
  **Polling Strategy:**

  * Wait 10-15 seconds before first poll (videos rarely complete faster)
  * Poll every 10 seconds for first minute
  * Increase to 30 seconds, then 60 seconds
  * Stop after 10 minutes and check for issues
</Tip>

**Use Webhooks Instead:**

* Use \[Webhooks]\(/api-reference/v2/API Documentation/WebhookIntegration) instead of polling for better performance
* Instant notifications when videos are ready
* Reduced API calls and better scalability
* Lower latency for end users

**Polling Schedule:**

| Time Elapsed | Poll Interval | Reason                        |
| ------------ | ------------- | ----------------------------- |
| 0-60s        | Every 10s     | Videos might complete quickly |
| 1-5min       | Every 30s     | Normal processing time        |
| 5-10min      | Every 60s     | Handling queue delays         |
| > 10min      | Stop          | Likely an issue, check logs   |

**Webhook vs Polling:**

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant API
    
    Note over Client,API: ❌ Polling (Not Recommended)
    loop Every 30 seconds
        Client->>API: GET /avatar_video/{id}
        API-->>Client: Status: processing
    end
    Client->>API: GET /avatar_video/{id}
    API-->>Client: Status: completed
    
    Note over Client,API: ✅ Webhooks (Recommended)
    Client->>API: POST /create_video_from_avatar (with webhook)
    Note over API: Video processes
    API->>Client: POST /webhook {video_url}
```

***

## Response Field Reference

### Completed Video Response

| Field                         | Type    | Description                  |
| ----------------------------- | ------- | ---------------------------- |
| `video_id` / `id`             | string  | Video identifier             |
| `status`                      | string  | Current status (`completed`) |
| `video_url`                   | string  | Download URL for MP4 file    |
| `cover_url`                   | string  | Thumbnail/cover image URL    |
| `duration` / `video_duration` | number  | Video length in seconds      |
| `title`                       | string  | Video title (if provided)    |
| `created_at`                  | integer | Unix timestamp of creation   |

### Processing Video Response

| Field             | Type    | Description                                |
| ----------------- | ------- | ------------------------------------------ |
| `video_id` / `id` | string  | Video identifier                           |
| `status`          | string  | Current status (`pending` or `processing`) |
| `created_at`      | integer | Unix timestamp                             |

### Failed Video Response

| Field             | Type    | Description                      |
| ----------------- | ------- | -------------------------------- |
| `video_id` / `id` | string  | Video identifier                 |
| `status`          | string  | Status (`failed`)                |
| `error.code`      | integer | Error code                       |
| `error.message`   | string  | Human-readable error description |
| `created_at`      | integer | Unix timestamp                   |

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Video Not Found (404)">
    **Error**: `Video ID does not exist`

    **Solutions:**

    * Verify video ID is correct
    * Check if video creation succeeded
    * Video IDs are case-sensitive
    * Ensure you're using the correct endpoint for video type
  </Accordion>

  <Accordion title="Generation Failed">
    **Error**: Status is `failed` with error object

    **Common Causes:**

    * Insufficient media quality
    * Invalid avatar/voice combination
    * Script too long for video length
    * API quota exceeded
    * Invalid template variables

    **Solutions:**

    * Check error message in response
    * Verify all input parameters are valid
    * Retry with corrected parameters
    * Check [Error Handling Guide](/api-reference/v2/QuickStart/ErrorHandling)
  </Accordion>

  <Accordion title="Processing Timeout">
    **Issue**: Video stuck in processing > 15 minutes

    **Solutions:**

    * Contact support with video ID
    * Check [Status Page](https://status.jogg.ai)
    * Retry video creation
    * Verify video type and parameters
  </Accordion>

  <Accordion title="Rate Limiting">
    **Error**: Too many requests

    **Solutions:**

    * Reduce polling frequency (minimum 5 seconds between polls)
    * Use webhooks instead of polling
    * Check [Rate Limits](/api-reference/v2/QuickStart/RateLimits)
    * Implement exponential backoff
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Webhook Integration" icon="webhook" href="/api-reference/v2/API Documentation/WebhookIntegration">
    Better alternative to polling
  </Card>

  <Card title="Create Avatar Videos" icon="user" href="/api-reference/v2/API Documentation/CreateAvatarVideos">
    Start video generation
  </Card>

  <Card title="Error Handling" icon="circle-exclamation" href="/api-reference/v2/QuickStart/ErrorHandling">
    Understand error responses
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/api-reference/v2/QuickStart/RateLimits">
    API usage limits
  </Card>
</CardGroup>


# Lip Sync Video
Source: https://docs.jogg.ai/api-reference/v2/API Documentation/LipSyncVideo

Create lip sync videos by combining a source video with a target audio track

## Introduction

Use the Lip Sync API to generate a new video where the speaker's mouth movement is synchronized to a target audio track. Submit a source video URL and an audio URL, then poll the task status until the final result is ready.

### Key Features

<CardGroup>
  <Card title="Async Processing" icon="bolt">
    Submit once and retrieve results when processing completes
  </Card>

  <Card title="Simple Input" icon="link">
    Create tasks with just a video URL and an audio URL
  </Card>

  <Card title="Flexible Playback" icon="play">
    Choose how to handle cases where video is shorter than audio
  </Card>

  <Card title="Result Metadata" icon="info-circle">
    Get output video URL, cover image, duration, and error details
  </Card>
</CardGroup>

### Workflow Overview

Lip sync video generation is an **asynchronous 3-step process**:

<Steps>
  <Step title="Submit Task">
    Call the create endpoint with your source video and source audio URLs
  </Step>

  <Step title="Processing">
    JoggAI performs lip sync generation in the background
  </Step>

  <Step title="Retrieve Result">
    Poll the task endpoint until status becomes `success` or `failed`
  </Step>
</Steps>

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant API
    participant Queue

    Note over Client,API: 1. Submit Task
    Client->>API: POST /v2/create_lip_sync_video
    API->>Queue: Queue lip sync task
    API-->>Client: 200 OK {task_id, status}

    Note over Queue: 2. Processing
    Queue->>Queue: Sync mouth movement to target audio

    Note over Client,API: 3. Poll Result
    loop Until finished
        Client->>API: GET /v2/lip_sync_video/{task_id}
        API-->>Client: {status, data?, error?}
    end
```

<Info>
  Lip sync generation is asynchronous. After submitting the task, store the returned `task_id` and use it to poll for progress and results.
</Info>

***

## Quick Start

### Related API Endpoints

| Endpoint                           | Purpose                    | Documentation                                               |
| ---------------------------------- | -------------------------- | ----------------------------------------------------------- |
| `POST /v2/create_lip_sync_video`   | Submit lip sync task       | [API Reference](/api-reference/v2/Video/CreateLipSyncVideo) |
| `GET /v2/lip_sync_video/{task_id}` | Check lip sync task status | [API Reference](/api-reference/v2/Video/GetLipSyncVideo)    |

### Key Parameters

| Parameter       | Type   | Required | Description                                               |
| --------------- | ------ | -------- | --------------------------------------------------------- |
| `video_url`     | string | ✅        | Publicly accessible source video URL                      |
| `audio_url`     | string | ✅        | Publicly accessible source audio URL                      |
| `playback_type` | string | ❌        | Playback behavior when source video is shorter than audio |

### Playback Type Values

| Value                     | Description                                                |
| ------------------------- | ---------------------------------------------------------- |
| `normal`                  | Play the source video normally                             |
| `normal_reverse`          | Alternate forward and reverse playback to extend the video |
| `normal_reverse_by_audio` | Extend playback dynamically based on source audio duration |

### Pricing

| Rule                        | Value                                |
| --------------------------- | ------------------------------------ |
| Credits per duration        | `1` credit per `125` seconds         |
| Approximate cost per second | `0.008` credits/second               |
| Display rule                | Round up and keep `2` decimal places |

<Info>
  Estimated usage can be calculated from output duration. Since `1 / 125 = 0.008`, the displayed unit cost is approximately `0.01` credits per second when rounded up to `2` decimal places.
</Info>

<Warning>
  The `video_url` and `audio_url` must be publicly accessible direct URLs. Temporary or authenticated links may fail during processing.
</Warning>

***

## Code Examples

### Step 1: Submit Lip Sync Task

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_lip_sync_video' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "video_url": "https://res.jogg.ai/source-video.mp4",
    "audio_url": "https://res.jogg.ai/source-audio.wav",
    "playback_type": "normal"
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "task_id": "3d5c6930-d0da-4f7b-826e-cd1530f6734f",
    "status": "pending"
  }
}
```

<Check>
  Save the `task_id` from the response. You will need it to poll the lip sync task result.
</Check>

***

### Step 2: Check Task Status

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/lip_sync_video/3d5c6930-d0da-4f7b-826e-cd1530f6734f' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response (Processing):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "task_id": "3d5c6930-d0da-4f7b-826e-cd1530f6734f",
    "status": "processing",
    "created_at": 1741500000,
    "completed_at": null,
    "data": null,
    "error": null
  }
}
```

**Response (Success):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "task_id": "3d5c6930-d0da-4f7b-826e-cd1530f6734f",
    "status": "success",
    "created_at": 1741500000,
    "completed_at": 1741500030,
    "data": {
      "result_url": "https://res.jogg.ai/lipsync-result.mp4",
      "cover_url": "https://res.jogg.ai/lipsync-cover.jpg",
      "duration_seconds": 12.5
    },
    "error": null
  }
}
```

**Response (Failed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "task_id": "3d5c6930-d0da-4f7b-826e-cd1530f6734f",
    "status": "failed",
    "created_at": 1741500000,
    "completed_at": 1741500030,
    "data": null,
    "error": {
      "message": "consume retry limit reached: audio duration fetch failed"
    }
  }
}
```

### Status Values

| Status       | Description                           | Action                  |
| ------------ | ------------------------------------- | ----------------------- |
| `pending`    | Task has been accepted and queued     | Wait, then poll again   |
| `processing` | Lip sync is currently being generated | Continue polling        |
| `success`    | Final video is ready                  | Download `result_url`   |
| `failed`     | Task could not be completed           | Inspect `error.message` |

<Tip>
  Poll every 5-10 seconds for active tasks. In production, avoid overly aggressive polling to reduce unnecessary API traffic.
</Tip>

***

## Use Case Examples

<AccordionGroup>
  <Accordion title="Dubbed social clips">
    Replace or localize speech in short-form videos while preserving the speaker's visual delivery.
  </Accordion>

  <Accordion title="Voice replacement workflows">
    Reuse an existing talking-head video with a different audio track for updated messaging or campaigns.
  </Accordion>

  <Accordion title="Batch content localization">
    Generate multiple lip sync tasks for different audio tracks and languages using the same base video.
  </Accordion>
</AccordionGroup>

***

## Tips for Best Results

<Tip>
  **Input quality matters:**

  * Use a clear frontal face shot when possible
  * Avoid heavy occlusion around the mouth area
  * Use clean audio with stable volume
  * Prefer publicly accessible CDN URLs over temporary download links
</Tip>

**Playback strategy guidance:**

* Use `normal` when video duration already matches the audio well
* Use `normal_reverse` when you want a simple loop-like extension effect
* Use `normal_reverse_by_audio` when alignment should adapt to the audio duration

**Polling guidance:**

* Start polling a few seconds after task creation
* Poll every 5-10 seconds during active processing
* Stop polling once status is `success` or `failed`

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Source URL cannot be fetched">
    **Issue:** Task fails because the video or audio file cannot be downloaded.

    **Solutions:**

    * Ensure both URLs are publicly accessible
    * Avoid signed URLs that expire too quickly
    * Verify the files are reachable from outside your network
    * Confirm the linked file is the actual media file, not an HTML preview page
  </Accordion>

  <Accordion title="Task remains processing for too long">
    **Issue:** Status stays `processing` longer than expected.

    **Solutions:**

    * Continue polling with a moderate interval
    * Retry with smaller or simpler media files if needed
    * Verify source media is stable and downloadable
    * Contact support if the task remains stuck for an extended period
  </Accordion>

  <Accordion title="Task failed with audio-related error">
    **Issue:** The API returns an audio parsing or duration error.

    **Solutions:**

    * Make sure the audio URL points to a valid audio file
    * Re-encode the audio into a common format such as WAV or MP3
    * Check whether the source URL returns partial or corrupted content
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Create Lip Sync Video Task" icon="code" href="/api-reference/v2/Video/CreateLipSyncVideo">
    Full request schema for submitting tasks
  </Card>

  <Card title="Get Lip Sync Video Task" icon="circle-check" href="/api-reference/v2/Video/GetLipSyncVideo">
    Full response schema for task status and result
  </Card>

  <Card title="Check Video Result & Status" icon="info-circle" href="/api-reference/v2/API Documentation/GetResult">
    General guidance for polling asynchronous video tasks
  </Card>

  <Card title="Webhook Integration" icon="webhook" href="/api-reference/v2/API Documentation/WebhookIntegration">
    Recommended callback pattern for async workflows
  </Card>
</CardGroup>


# Create Video from URL/Product
Source: https://docs.jogg.ai/api-reference/v2/API Documentation/URLtoVideo

Generate marketing videos automatically from product URLs or descriptions

## Introduction

Transform product URLs or descriptions into professional marketing videos automatically. JoggAI analyzes your product, generates AI scripts, and creates complete videos with avatars and voiceovers.

### Key Features

<CardGroup>
  <Card title="URL Analysis" icon="link">
    Extract product info from any URL automatically
  </Card>

  <Card title="AI Scripts" icon="wand-magic-sparkles">
    Generate marketing scripts with AI
  </Card>

  <Card title="Visual Styles" icon="palette">
    Choose from 50+ professional templates
  </Card>

  <Card title="Multi-Language" icon="language">
    Create videos in 40+ languages
  </Card>
</CardGroup>

### Workflow Overview

Product video generation is a **3-step asynchronous process**:

<Steps>
  <Step title="Create Product">
    Submit product URL or manual details
  </Step>

  <Step title="Generate Video">
    Select avatar, voice, visual style, and script
  </Step>

  <Step title="Get Result">
    Retrieve video via webhook or polling (5-10 minutes)
  </Step>
</Steps>

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant API
    participant AI
    participant Queue
    
    Note over Client,AI: Step 1: Create Product
    Client->>API: POST /product {url}
    API->>AI: Extract product info
    API-->>Client: 200 OK {product_id}
    
    Note over Client,Queue: Step 2: Generate Video
    Client->>API: POST /create_video_from_product
    API->>Queue: Queue rendering
    API-->>Client: 200 OK {product_video_id}
    
    Note over Queue: Step 3: Processing (5-10 min)
    Queue->>Queue: Generate video
    
    alt Webhook
        Queue->>Client: POST /webhook {video_url}
    else Polling
        Client->>API: GET /product_video/{product_video_id}
        API-->>Client: {video_url, status}
    end
```

<Info>
  The entire process can take **5-10 minutes** depending on video complexity. Use webhooks for best experience.
</Info>

***

## Quick Start

### Related API Endpoints

| Endpoint                                                   | Purpose                         | Documentation                                                   |
| ---------------------------------------------------------- | ------------------------------- | --------------------------------------------------------------- |
| `POST /v2/product`                                         | Create product entry            | [API Reference](/api-reference/v2/Product/CreateProduct)        |
| `GET /v2/avatars/public`                                   | Get avatar list                 | [API Reference](/api-reference/v2/Avatar/PublicAvatarsGet)      |
| `GET /v2/voices`                                           | Get voice list                  | [API Reference](/api-reference/v2/Voice/GetVoices)              |
| `GET /v2/visual_styles`                                    | Get visual styles               | [API Reference](/api-reference/v2/Asset/GetVisualStyles)        |
| `POST /v2/create_video_from_product/preview_list`          | Generate previews               | [API Reference](/api-reference/v2/Video/SubmitPreviewList)      |
| `POST /v2/create_video_from_product/render_single_preview` | Render final video from preview | [API Reference](/api-reference/v2/Video/RenderSinglePreview)    |
| `POST /v2/create_video_from_product`                       | Generate video directly         | [API Reference](/api-reference/v2/Video/CreateVideoFromProduct) |
| `GET /v2/product_video/{product_video_id}`                 | Check status                    | [API Reference](/api-reference/v2/Video/ProductVideoGet)        |

### Key Parameters

**Create Product (Step 1):**

| Parameter         | Type   | Required | Description                       |
| ----------------- | ------ | -------- | --------------------------------- |
| `url`             | string | \*       | Product URL (required if no name) |
| `name`            | string | \*       | Product name (required if no URL) |
| `description`     | string | ❌        | Product description               |
| `target_audience` | string | ❌        | Target audience description       |
| `media`           | array  | ❌        | Product images/videos array       |

**Generate Video (Step 2):**

| Parameter         | Type    | Required | Description                            |
| ----------------- | ------- | -------- | -------------------------------------- |
| `product_id`      | string  | ✅        | Product ID from Step 1                 |
| `aspect_ratio`    | string  | ✅        | portrait/landscape/square              |
| `video_length`    | string  | ✅        | "15"/"30"/"60" seconds                 |
| `language`        | string  | ✅        | Script language (e.g., "english")      |
| `avatar_id`       | integer | ✅        | Avatar ID                              |
| `avatar_type`     | integer | ✅        | 0=Public, 1=Custom                     |
| `script_style`    | string  | ✅        | Script style (see Script Styles below) |
| `visual_style`    | string  | ❌        | Visual template name                   |
| `voice_id`        | string  | ❌        | Voice ID for TTS                       |
| `music_id`        | integer | ❌        | Background music ID                    |
| `override_script` | string  | ❌        | Custom script to override AI-generated |
| `template_id`     | integer | ❌        | Custom template ID                     |
| `template_type`   | string  | ❌        | "custom" or "public"                   |
| `caption`         | boolean | ❌        | Enable subtitles (default: false)      |

<Warning>
  **Product Creation:** You must provide either `url` OR `name` (at least one is required). Providing both is also valid.
</Warning>

***

## Code Examples

### Step 1: Create Product Entry

**Option A: From Product URL**

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/product' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://www.amazon.com/dp/B0BX7CVAPM"
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "product_id": "NTIzMzc0NjI5",
    "name": "Owala FreeSip Water Bottle",
    "description": "Insulated stainless steel water bottle...",
    "media": [
      {
        "type": 1,
        "url": "https://m.media-amazon.com/images/I/61wvLrf8ekL._AC_SL1500_.jpg"
      }
    ]
  }
}
```

**Option B: Manual Product Details**

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/product' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Premium Yoga Mat",
    "description": "Eco-friendly yoga mat with superior grip and cushioning. Perfect for all yoga styles.",
    "target_audience": "Yoga enthusiasts and fitness lovers",
    "media": [
      {
        "type": 1,
        "name": "product-image.jpg",
        "url": "https://example.com/yoga-mat.jpg",
        "description": "Main product image"
      }
    ]
  }'
```

<Check>
  Save the `product_id` from the response - you'll need it for video generation!
</Check>

***

### Step 2: Generate Video

Create video with AI-generated script:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_from_product' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "product_id": "NTIzMzc0NjI5",
    "visual_style": "Simple Product Switch",
    "video_spec": {
      "aspect_ratio": "portrait",
      "length": "30",
      "caption": true
    },
    "avatar": {
      "id": 81,
      "type": 0
    },
    "voice": {
      "id": "en-US-ChristopherNeural"
    },
    "audio": {},
    "script": {
      "style": "Storytime",
      "language": "english"
    }
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "product_video_id": "pv_123456"
  }
}
```

<Check>
  Save the `product_video_id` to check status later!
</Check>

***

### Step 3: Check Video Status

Poll to check if video is ready:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/product_video/pv_123456' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response (Processing):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "id": "pv_123456",
    "status": "processing"
  }
}
```

**Response (Completed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "id": "pv_123456",
    "status": "completed",
    "video_url": "https://res.jogg.ai/videos/pv_123456.mp4",
    "cover_url": "https://res.jogg.ai/covers/pv_123456.jpg",
    "duration": 30
  }
}
```

<Tip>
  Instead of polling, use \[Webhooks]\(/api-reference/v2/API Documentation/WebhookIntegration) to get notified instantly when videos are ready!
</Tip>

***

## Advanced Examples

### Custom Script Override

Override the AI-generated script with your own:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_from_product' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "product_id": "NTIzMzc0NjI5",
    "video_spec": {
      "aspect_ratio": "landscape",
      "length": "30",
      "caption": true
    },
    "avatar": {
      "id": 81,
      "type": 0
    },
    "voice": {
      "id": "en-US-ChristopherNeural"
    },
    "audio": {},
    "script": {
      "style": "Storytime",
      "language": "english"
    },
    "override_script": "Check out this amazing water bottle! It keeps your drinks cold for 24 hours and features a unique FreeSip spout. Perfect for the gym or outdoor adventures!"
  }'
```

<Tip>
  Use `override_script` when you have a specific message or want full control over the narration.
</Tip>

***

### Using Background Music

Add background music to your product video:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_from_product' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "product_id": "NTIzMzc0NjI5",
    "video_spec": {
      "aspect_ratio": "square",
      "length": "15",
      "caption": false
    },
    "avatar": {
      "id": 81,
      "type": 0
    },
    "voice": {
      "id": "en-US-ChristopherNeural"
    },
    "audio": {
      "music_id": 13
    },
    "script": {
      "style": "Discovery",
      "language": "english"
    }
  }'
```

<Info>
  Get available background music using [Get Music API](/api-reference/v2/Asset/GetMusic).
</Info>

***

### Preview Multiple Styles

Generate previews with different visual styles before committing to a final video. This is useful for testing and comparing different styles:

**Step 1: Submit Preview List**

Generate multiple previews with different visual styles:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_from_product/preview_list' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "product_id": "NTIzMzc0NjI5",
    "visual_styles": ["Simple Product Switch", "Dynamic Showcase", "Elegant Presentation"],
    "video_spec": {
      "aspect_ratio": "portrait",
      "length": "30",
      "caption": true
    },
    "avatar": {
      "id": 81,
      "type": 0
    },
    "voice": {
      "id": "en-US-ChristopherNeural"
    },
    "audio": {},
    "script": {
      "style": "Storytime",
      "language": "english"
    }
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "preview_list_id": "pl_123456",
    "previews": [
      {
        "preview_id": "preview_001",
        "visual_style": "Simple Product Switch",
        "status": "processing"
      },
      {
        "preview_id": "preview_002",
        "visual_style": "Dynamic Showcase",
        "status": "processing"
      },
      {
        "preview_id": "preview_003",
        "visual_style": "Elegant Presentation",
        "status": "processing"
      }
    ]
  }
}
```

<Info>
  Preview generation typically takes **2-3 minutes**. Check preview status using the `preview_id` from the response.
</Info>

**Step 2: Render Final Video from Preview**

Once previews are ready, select your preferred preview and render the final video:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_from_product/render_single_preview' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "preview_id": "preview_001"
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "product_video_id": "pv_123456"
  }
}
```

<Tip>
  **When to use previews:**

  * Testing multiple visual styles before committing to final video
  * Comparing different styles for A/B testing
  * Ensuring quality before generating full video
  * Saving credits by previewing first
</Tip>

***

## Script Styles Reference

Choose the right script style for your product:

| Style               | Best For              | Tone                   |
| ------------------- | --------------------- | ---------------------- |
| **Storytime**       | Narrative products    | Engaging, story-driven |
| **Discovery**       | New products          | Exciting, exploratory  |
| **Don't Worry**     | Problem-solving       | Reassuring, helpful    |
| **Data**            | Tech products         | Factual, informative   |
| **Top 3 Reasons**   | Feature-rich products | Clear, structured      |
| **Light Marketing** | General products      | Friendly, promotional  |

***

## Use Case Examples

<AccordionGroup>
  <Accordion title="E-commerce Product Videos">
    Automate product video creation for online stores:

    * Bulk generate videos for entire catalog
    * Use portrait format for mobile shopping
    * Enable captions for silent browsing
    * Try multiple script styles for A/B testing
  </Accordion>

  <Accordion title="Social Media Advertising">
    Create scroll-stopping ads:

    * Use "Storytime" or "Discovery" styles
    * Keep videos short (15-30 seconds)
    * Choose engaging avatars
    * Add background music for emotion
  </Accordion>

  <Accordion title="Marketplace Listings">
    Enhance Amazon/eBay listings:

    * Extract info directly from product URLs
    * Generate in multiple languages for global markets
    * Use landscape format for desktop viewers
    * Highlight key features with "Top 3 Reasons"
  </Accordion>

  <Accordion title="Dropshipping Business">
    Scale video content creation:

    * Batch process product URLs
    * Customize scripts for your brand voice
    * Generate localized versions
    * Use webhook automation for efficiency
  </Accordion>
</AccordionGroup>

***

## Tips for Best Results

<Tip>
  **Product Information:**

  * Provide detailed product descriptions for better AI script generation
  * Include target audience information for personalized scripts
  * Add high-quality product images for better visual results
  * Use clear, descriptive product names
</Tip>

**Script Style Selection:**

* Use "Storytime" for lifestyle products
* Use "Data" for technical products with specifications
* Use "Top 3 Reasons" to highlight key features
* Test different styles to find what works best for your products

**Video Configuration:**

* Use portrait format (9:16) for social media platforms
* Use landscape format (16:9) for YouTube and websites
* Enable captions for better engagement and accessibility
* Choose appropriate video length based on platform (15s for TikTok, 30-60s for YouTube)

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Product URL not accessible">
    **Error:** `Failed to extract product information`

    **Solutions:**

    * Ensure URL is publicly accessible (no login required)
    * Check if URL is from a supported marketplace (Amazon, eBay, etc.)
    * Try providing product details manually instead
    * Verify URL format is correct
  </Accordion>

  <Accordion title="Video generation fails">
    **Error:** `Video generation failed`

    **Solutions:**

    * Verify product\_id is correct and product was created successfully
    * Check that all required parameters are provided
    * Ensure avatar\_id and script\_style are valid
    * Check API quota/credits balance
  </Accordion>

  <Accordion title="Script quality issues">
    **Issue:** Generated script doesn't match product

    **Solutions:**

    * Provide more detailed product description
    * Specify target\_audience for better personalization
    * Try different script\_style options
    * Use override\_script for full control
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="AI Script Generation" icon="wand-magic-sparkles" href="/api-reference/v2/API Documentation/AIScripts">
    Generate custom scripts with AI
  </Card>

  <Card title="Template Videos" icon="file-video" href="/api-reference/v2/API Documentation/CreateVideoFromTemplate">
    Use templates for consistent branding
  </Card>

  <Card title="Upload Media" icon="upload" href="/api-reference/v2/API Documentation/UploadMedia">
    Add custom product images
  </Card>

  <Card title="Webhook Integration" icon="webhook" href="/api-reference/v2/API Documentation/WebhookIntegration">
    Automate video delivery
  </Card>

  <Card title="Submit Preview List" icon="eye" href="/api-reference/v2/Video/SubmitPreviewList">
    Generate multiple previews with different styles
  </Card>

  <Card title="Render Single Preview" icon="play" href="/api-reference/v2/Video/RenderSinglePreview">
    Render final video from selected preview
  </Card>
</CardGroup>


# Upload Media Assets
Source: https://docs.jogg.ai/api-reference/v2/API Documentation/UploadMedia

Upload images, videos, and audio files to use in your video projects

## Introduction

Upload custom media assets to JoggAI to enhance your videos. Include branded images, product photos, background videos, custom audio, and more in your video creation projects.

### Key Features

<CardGroup>
  <Card title="Multiple Formats" icon="file">
    Support for images, videos, and audio
  </Card>

  <Card title="Easy Integration" icon="plug">
    Reference assets by ID in video creation
  </Card>

  <Card title="Organized Storage" icon="folder">
    Organize assets into folders
  </Card>

  <Card title="Reusable Assets" icon="recycle">
    Upload once, use in multiple projects
  </Card>
</CardGroup>

### Workflow Overview

<Steps>
  <Step title="Get Signed URL">
    Request upload URL with file metadata
  </Step>

  <Step title="Upload File">
    Upload file using PUT request to signed URL
  </Step>

  <Step title="Use Asset URL">
    Use asset\_url from Step 1 in video creation
  </Step>
</Steps>

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant API
    participant Storage
    
    Note over Client,Storage: Step 1: Get Signed URL
    Client->>API: POST /v2/upload/asset {filename, content_type}
    API-->>Client: {sign_url, asset_url}
    
    Note over Client,Storage: Step 2: Upload File
    Client->>Storage: PUT sign_url {file binary}
    Storage-->>Client: 200 OK
    
    Note over Client,Storage: Step 3: Use in Video
    Client->>API: POST /create_video_from_avatar {asset_url}
    API-->>Client: Video with custom asset
```

<Info>
  Assets are stored permanently and can be reused across multiple video projects.
</Info>

***

## Quick Start

### Related API Endpoints

| Endpoint                         | Purpose              | Documentation                                                  |
| -------------------------------- | -------------------- | -------------------------------------------------------------- |
| `POST /upload/asset`             | Upload media file    | [API Reference](/api-reference/v2/Asset/UploadAsset)           |
| `POST /create_video_from_avatar` | Use assets in videos | [API Reference](/api-reference/v2/Video/CreateVideoFromAvatar) |

### Key Parameters

| Parameter      | Type    | Required | Description                                               |
| -------------- | ------- | -------- | --------------------------------------------------------- |
| `filename`     | string  | ✅        | Name of the file to upload                                |
| `content_type` | string  | ✅        | MIME type (e.g., "image/jpeg", "video/mp4", "audio/mpeg") |
| `file_size`    | integer | ❌        | File size in bytes (optional)                             |

***

## Code Examples

### Scenario 1: Upload Image

Upload product photos, logos, or background images:

**Step 1: Get Signed URL**

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/upload/asset' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "filename": "product.jpg",
    "content_type": "image/jpeg",
    "file_size": 245678
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "sign_url": "https://storage.jogg.ai/upload/signed-url-here",
    "asset_url": "https://res.jogg.ai/assets/img_abc123.jpg"
  }
}
```

**Step 2: Upload File Using PUT**

```bash theme={null}
curl --request PUT \
  --url 'https://storage.jogg.ai/upload/signed-url-here' \
  --header 'Content-Type: image/jpeg' \
  --data-binary '@/path/to/product.jpg'
```

<Check>
  After successful PUT upload, use the `asset_url` from Step 1 response in your video creation requests.
</Check>

**Supported Image Formats:**

| Format | Max Size | Best For                 |
| ------ | -------- | ------------------------ |
| JPG    | 10MB     | Photos, product images   |
| PNG    | 10MB     | Images with transparency |
| WebP   | 10MB     | Modern, efficient format |
| GIF    | 10MB     | Animated images          |

<Check>
  Recommended resolution: 1920x1080 or higher
</Check>

***

### Scenario 2: Upload Video

Upload background videos or product demos:

**Step 1: Get Signed URL**

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/upload/asset' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "filename": "demo.mp4",
    "content_type": "video/mp4",
    "file_size": 8456789
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "sign_url": "https://storage.jogg.ai/upload/signed-url-here",
    "asset_url": "https://res.jogg.ai/assets/vid_def456.mp4"
  }
}
```

**Step 2: Upload File Using PUT**

```bash theme={null}
curl --request PUT \
  --url 'https://storage.jogg.ai/upload/signed-url-here' \
  --header 'Content-Type: video/mp4' \
  --data-binary '@/path/to/demo.mp4'
```

**Supported Video Formats:**

| Format | Max Size | Max Duration | Best For           |
| ------ | -------- | ------------ | ------------------ |
| MP4    | 100MB    | 5 minutes    | Best compatibility |
| WebM   | 100MB    | 5 minutes    | Web optimized      |
| MOV    | 100MB    | 5 minutes    | High quality       |

<Warning>
  Videos longer than 5 minutes will be rejected. Codec: H.264/H.265
</Warning>

***

### Scenario 3: Upload Audio

Upload custom voiceovers or background music:

**Step 1: Get Signed URL**

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/upload/asset' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "filename": "music.mp3",
    "content_type": "audio/mpeg",
    "file_size": 3456789
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "sign_url": "https://storage.jogg.ai/upload/signed-url-here",
    "asset_url": "https://res.jogg.ai/assets/aud_ghi789.mp3"
  }
}
```

**Step 2: Upload File Using PUT**

```bash theme={null}
curl --request PUT \
  --url 'https://storage.jogg.ai/upload/signed-url-here' \
  --header 'Content-Type: audio/mpeg' \
  --data-binary '@/path/to/music.mp3'
```

**Supported Audio Formats:**

| Format | Max Size | Max Duration | Best For                 |
| ------ | -------- | ------------ | ------------------------ |
| MP3    | 20MB     | 10 minutes   | Best compatibility       |
| WAV    | 20MB     | 10 minutes   | Highest quality          |
| M4A    | 20MB     | 10 minutes   | Good quality, small size |

<Tip>
  Recommended: MP3 at 192 kbps for music, 128 kbps for voice
</Tip>

***

### Scenario 4: Use Uploaded Assets in Video

Reference uploaded assets in video creation:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_from_avatar' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "avatar_id": 81,
    "avatar_type": 0,
    "voice_id": "en-US-ChristopherNeural",
    "script": "Check out our amazing product!",
    "aspect_ratio": "portrait",
    "screen_style": 1,
    "background_image": "img_abc123",
    "background_music": "aud_ghi789"
  }'
```

<Info>
  Use `asset_id` values to reference your uploaded assets in any video creation endpoint.
</Info>

***

## Format Specifications

### Images

**Recommended Settings:**

* Resolution: 1920x1080 (1080p) or higher
* Quality: 80-90% for JPG
* Format: JPG for photos, PNG for transparency

**Optimization:**

```bash theme={null}
# Using ImageMagick
convert input.jpg -resize 1920x1080 -quality 85 output.jpg

# Using FFmpeg for WebP
ffmpeg -i input.jpg -q:v 80 output.webp
```

***

### Videos

**Recommended Settings:**

* Resolution: 1920x1080 (1080p)
* Codec: H.264
* Bitrate: 5-8 Mbps
* Frame Rate: 24, 30, or 60 fps
* Audio: AAC, 192 kbps

**Optimization:**

```bash theme={null}
# Using FFmpeg
ffmpeg -i input.mp4 \
  -vcodec h264 \
  -crf 23 \
  -preset medium \
  -vf scale=1920:1080 \
  -acodec aac \
  -b:a 192k \
  output.mp4
```

***

### Audio

**Recommended Settings:**

* **Music**: MP3, 192-256 kbps, Stereo
* **Voice**: MP3, 128-192 kbps, Mono
* Sample Rate: 44.1 kHz

**Optimization:**

```bash theme={null}
# Convert to MP3 at 192kbps
ffmpeg -i input.wav -codec:a libmp3lame -b:a 192k output.mp3

# Normalize audio levels
ffmpeg -i input.mp3 -filter:a loudnorm output.mp3
```

***

## Use Case Examples

<AccordionGroup>
  <Accordion title="E-commerce Product Videos">
    Upload product images and demo videos:

    * Product photos in multiple angles
    * Usage demonstration videos
    * Brand logos and watermarks
    * Background music for product showcases
  </Accordion>

  <Accordion title="Corporate Videos">
    Create professional corporate content:

    * Company logos and branding
    * Office or facility videos
    * Employee photos
    * Corporate audio branding
  </Accordion>

  <Accordion title="Social Media Content">
    Build engaging social media videos:

    * Eye-catching graphics
    * Short video clips
    * Trending audio tracks
    * Branded visual elements
  </Accordion>

  <Accordion title="Educational Content">
    Enhance learning materials:

    * Diagrams and charts
    * Demonstration videos
    * Background music
    * Custom voiceovers
  </Accordion>
</AccordionGroup>

***

## Best Practices

### Before Uploading

<Tip>
  * **Compress files** to reduce upload time and storage
  * **Test files locally** to ensure they're not corrupted
  * **Use appropriate formats** (JPG for photos, MP4 for videos, MP3 for audio)
  * **Optimize quality** - balance between quality and file size
</Tip>

### Organization

* Use **descriptive names** for easy identification
* Leverage **folder parameter** to organize by project or type
* **Document asset IDs** in your project management system
* Maintain a **local backup** of original files

### File Size Limits

| Asset Type | Max Size | Recommendation    |
| ---------- | -------- | ----------------- |
| Images     | 10MB     | Aim for 500KB-2MB |
| Videos     | 100MB    | Aim for 20-50MB   |
| Audio      | 20MB     | Aim for 2-5MB     |

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="File Too Large">
    **Error**: `File size exceeds limit`

    **Solutions:**

    * **Images**: Reduce resolution or quality (use 80-85% quality for JPG)
    * **Videos**: Lower bitrate, reduce resolution, or shorten duration
    * **Audio**: Convert to MP3, reduce bitrate to 128-192 kbps
    * **General**: Compress before upload using tools like FFmpeg or ImageMagick
  </Accordion>

  <Accordion title="Unsupported Format">
    **Error**: `File format not supported`

    **Solutions:**

    * Convert to supported format (JPG/PNG for images, MP4 for videos, MP3 for audio)
    * Check file extension matches actual format
    * Ensure file is not corrupted
    * For videos, ensure codec is H.264
  </Accordion>

  <Accordion title="Upload Failed">
    **Error**: `Upload failed` or timeout

    **Solutions:**

    * Check internet connection stability
    * Verify API key is valid and has upload permissions
    * Ensure file path is correct
    * Try compressing the file first
    * Retry with exponential backoff
  </Accordion>

  <Accordion title="Quality Issues">
    **Problem**: Uploaded asset looks poor quality

    **Solutions:**

    * Upload higher resolution original files
    * Don't upscale low-resolution images
    * For JPG, use 85-90% quality setting
    * For videos, use appropriate bitrate (5-8 Mbps for 1080p)
    * For audio, use at least 192 kbps for music
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Create Avatar Videos" icon="user" href="/api-reference/v2/API Documentation/CreateAvatarVideos">
    Use uploaded assets in avatar videos
  </Card>

  <Card title="Product Videos" icon="shopping-bag" href="/api-reference/v2/API Documentation/URLtoVideo">
    Include custom media in product videos
  </Card>

  <Card title="Template Videos" icon="layer-group" href="/api-reference/v2/API Documentation/CreateVideoFromTemplate">
    Use assets in video templates
  </Card>

  <Card title="Upload API Reference" icon="code" href="/api-reference/v2/Asset/UploadAsset">
    Detailed API documentation
  </Card>
</CardGroup>


# Video Translation
Source: https://docs.jogg.ai/api-reference/v2/API Documentation/VideoTranslation

Translate videos into 40+ languages with AI-powered voiceover and subtitles

## Introduction

Expand your video content to global audiences by translating videos into 40+ languages with natural-sounding AI voiceovers and synchronized subtitles. No need to re-record or hire translators - simply provide your video URL and target language.

### Key Features

<CardGroup>
  <Card title="40+ Languages" icon="globe">
    Support for major European, Asian, and other languages
  </Card>

  <Card title="AI Voiceover" icon="microphone">
    Natural-sounding voices matching original tone
  </Card>

  <Card title="Auto Subtitles" icon="closed-captioning">
    Synchronized subtitles generated automatically
  </Card>

  <Card title="Fast Processing" icon="bolt">
    10-20 minutes average turnaround time
  </Card>
</CardGroup>

### Workflow Overview

Video translation is a **4-step asynchronous process**:

<Steps>
  <Step title="Get Resources">
    Get supported languages and available voices
  </Step>

  <Step title="Submit Translation">
    Submit your video URL, target language, and voice selection
  </Step>

  <Step title="Processing">
    AI translates audio and generates voiceover (10-20 min)
  </Step>

  <Step title="Retrieve Result">
    Get translated video and subtitle files
  </Step>
</Steps>

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant API
    participant Queue
    
    Note over Client: 1. Get Resources
    Client->>API: GET /video_translate/target_languages
    API-->>Client: Supported languages list
    Client->>API: GET /voices?language=spanish
    API-->>Client: Available voices
    
    Note over Client,Queue: 2. Submit Translation
    Client->>API: POST /video_translate/
    API->>Queue: Queue translation task
    API-->>Client: 200 OK {video_translate_id}
    
    Note over Queue: 3. Processing (10-20 min)
    Queue->>Queue: Translate audio & generate voiceover
    
    Note over Client,Queue: 4. Get Result
    alt Webhook
        Queue->>Client: POST /callback {video_url, subtitle_url}
    else Polling
        Client->>API: GET /video_translate/{id}
        API-->>Client: {status, url, subtitle_url}
    end
```

<Info>
  **Video Duration Limit:** Videos must be between 0-3 minutes in length.
  Processing time: 10-20 minutes for typical videos (varies by length). Use webhooks or polling to get results.
</Info>

***

## Quick Start

### Related API Endpoints

| Endpoint                                       | Purpose                                   | Documentation                                                              |
| ---------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------- |
| `GET /v2/video_translate/target_languages`     | Get supported languages                   | [API Reference](/api-reference/v2/Video/VideoTranslateTargetLanguagesList) |
| `GET /v2/voices`                               | Get available voices (filter by language) | [API Reference](/api-reference/v2/Voice/GetVoices)                         |
| `POST /v2/video_translate/`                    | Submit translation task                   | [API Reference](/api-reference/v2/Video/VideoTranslateCreate)              |
| `GET /v2/video_translate/{video_translate_id}` | Check translation status                  | [API Reference](/api-reference/v2/Video/VideoTranslateGet)                 |

### Key Parameters

| Parameter                 | Type    | Required | Description                                                                           |
| ------------------------- | ------- | -------- | ------------------------------------------------------------------------------------- |
| `video_url`               | string  | ✅        | URL of the video to translate (must be publicly accessible, **0-3 minutes duration**) |
| `output_language`         | string  | ✅        | Target language name (e.g., "spanish", "french", "japanese")                          |
| `output_voice`            | string  | ❌        | Specific voice ID for target language (auto-selected if omitted)                      |
| `add_subtitles`           | boolean | ❌        | Generate subtitle file (.srt) (default: true)                                         |
| `title`                   | string  | ❌        | Title for the translated video                                                        |
| `translate_audio_only`    | boolean | ❌        | Translate audio only without lip sync (default: false)                                |
| `enable_dynamic_duration` | boolean | ❌        | Enable dynamic duration adjustment (default: false)                                   |
| `callback_url`            | string  | ❌        | Callback URL for status notifications                                                 |

<Warning>
  **Video Requirements:**

  * Video duration must be **0-3 minutes**
  * Video URL must be publicly accessible without authentication
  * Supported formats: MP4, MOV, AVI
</Warning>

<Tip>
  Use the `/target_languages` endpoint to get the complete up-to-date list. Language names are in lowercase English (e.g., "spanish" not "es").
</Tip>

***

## Code Examples

### Step 1: Get Supported Languages

List all available target languages:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/video_translate/target_languages' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "languages": ["spanish", "french", "german", "japanese", "chinese", "korean"]
  }
}
```

***

### Step 2: Get Available Voices for Target Language

Get voices available for your target language:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/voices?language=spanish' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "voices": [
      {
        "name": "Elvira",
        "voice_id": "es-ES-ElviraNeural",
        "language": "spanish",
        "gender": "female",
        "age": "young",
        "accent": "spanish",
        "audio_url": "https://res.jogg.ai/voice-sample.mp3"
      },
      {
        "name": "Alvaro",
        "voice_id": "es-ES-AlvaroNeural",
        "language": "spanish",
        "gender": "male",
        "age": "young",
        "accent": "spanish",
        "audio_url": "https://res.jogg.ai/voice-sample.mp3"
      }
    ],
    "has_more": false
  }
}
```

<Check>
  Save the `voice_id` from the response to use as `output_voice` in translation request. You can filter by `gender` and `age` if needed.
</Check>

***

### Step 3: Submit Translation Task

Submit your video for translation:

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/video_translate/' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "video_url": "https://example.com/original-video.mp4",
    "output_language": "spanish",
    "output_voice": "es-ES-ElviraNeural",
    "add_subtitles": true
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_translate_id": "vt_123456"
  }
}
```

<Check>
  Save the `video_translate_id` to check status later!
</Check>

***

### Step 4: Check Translation Status

Poll to check if translation is ready:

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/video_translate/vt_123456' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response (Processing):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_translate_id": "vt_123456",
    "title": "Translated Video Title",
    "status": "processing"
  }
}
```

**Response (Completed):**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "video_translate_id": "vt_123456",
    "title": "Translated Video Title",
    "status": "completed",
    "url": "https://res.jogg.ai/translated_video.mp4",
    "subtitle_url": "https://res.jogg.ai/subtitle.srt"
  }
}
```

**Status Values:**

| Status       | Description             | Action                       |
| ------------ | ----------------------- | ---------------------------- |
| `pending`    | Task queued             | Wait for processing          |
| `processing` | Translation in progress | Continue polling (every 10s) |
| `completed`  | Translation finished    | Download video and subtitles |
| `failed`     | Translation failed      | Check error message          |

<Tip>
  Instead of polling, use \[Webhooks]\(/api-reference/v2/API Documentation/WebhookIntegration) to get notified instantly when translations are ready!
</Tip>

***

## Use Case Examples

<AccordionGroup>
  <Accordion title="E-commerce Product Videos">
    Translate product demos for international markets:

    * Get voices for target market language
    * Submit translation with appropriate voice
    * Generate localized product videos
    * Reach global customers effectively
  </Accordion>

  <Accordion title="Educational Content">
    Translate training videos for global teams:

    * Batch translate to multiple languages
    * Use consistent voice across languages
    * Enable subtitles for better comprehension
    * Scale training content globally
  </Accordion>

  <Accordion title="Marketing Campaigns">
    Localize marketing videos for different regions:

    * Translate to regional languages
    * Choose voices matching brand identity
    * Maintain message consistency
    * Reduce production costs
  </Accordion>

  <Accordion title="Customer Support">
    Create multilingual support videos:

    * Translate FAQ and tutorial videos
    * Use clear, professional voices
    * Enable subtitles for accessibility
    * Improve customer experience globally
  </Accordion>
</AccordionGroup>

***

## Tips for Best Results

<Tip>
  **Source Video Quality:**

  * Use clear audio with minimal background noise
  * Moderate speaking pace (not too fast)
  * Standard accent and clear pronunciation
  * Avoid complex jargon, idioms, or slang
  * Ensure speech track is clearly audible
</Tip>

**Voice Selection:**

* Match gender and approximate age to original
* Consider formal vs casual tone
* Test different voices with short clips
* Use `/voices?language={language}` to preview available voices
* Choose appropriate `output_voice` based on preferences

**Subtitle Usage:**

* ✅ Improves comprehension accuracy
* ✅ Helps viewers in noisy environments
* ✅ Accessibility for hearing impaired
* ✅ Aids language learning
* ✅ Enabled by default with `add_subtitles: true`

**Batch Processing:**

* Submit all tasks at once (parallel processing)
* Use descriptive task tracking
* Implement webhook for completion notification
* Handle failures gracefully (retry logic)
* Monitor API rate limits

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Translation takes too long">
    **Issue:** Processing exceeds expected time

    **Solutions:**

    * Video length impacts processing time (2-5 min per minute of video)
    * Verify video URL is publicly accessible
    * Check video file size (very large files take longer)
    * Check current API status for delays
    * Use webhook to get notified when complete
  </Accordion>

  <Accordion title="Poor voiceover quality">
    **Issue:** Translated audio doesn't sound natural

    **Solutions:**

    * Try different `output_voice` values for target language
    * Ensure original audio is clear (low background noise)
    * Check if original speech pace is too fast
    * Enable subtitles for better context
    * Test with high-quality source video first
  </Accordion>

  <Accordion title="Video not accessible">
    **Error:** `Video URL not accessible`

    **Solutions:**

    * Ensure URL is publicly accessible (no authentication)
    * Check CORS/download restrictions
    * Verify video format is supported (MP4, MOV, AVI)
    * Try uploading to a CDN first
    * Check URL is not expired or temporary
  </Accordion>

  <Accordion title="Translation inaccurate">
    **Issue:** Translated content doesn't match original

    **Solutions:**

    * Original audio may not be clear enough
    * Check for heavy accents or dialects
    * Avoid technical jargon or domain-specific terms
    * Consider adding subtitles to original first
    * Test with simpler, clearer speech
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup>
  <Card title="Get Voices" icon="microphone" href="/api-reference/v2/Voice/GetVoices">
    Browse all available voices
  </Card>

  <Card title="Webhook Integration" icon="webhook" href="/api-reference/v2/API Documentation/WebhookIntegration">
    Get notified when translation completes
  </Card>

  <Card title="Get Result" icon="circle-check" href="/api-reference/v2/API Documentation/GetResult">
    How to check task status
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/v2/Video/VideoTranslateCreate">
    Complete API documentation
  </Card>
</CardGroup>


# Webhook Integration Guide
Source: https://docs.jogg.ai/api-reference/v2/API Documentation/WebhookIntegration

Receive real-time notifications when your videos are ready

## Overview

JoggAI sends HTTP POST requests to your webhook endpoint when events occur (like video completion). This eliminates the need for polling and provides instant notifications.

<Info>
  **Webhook Limit**: Each user can create up to **20** webhook endpoints.
</Info>

<CardGroup>
  <Card title="Real-Time Updates" icon="bolt">
    Get notified instantly when videos complete
  </Card>

  <Card title="Reduced API Calls" icon="arrows-down-to-line">
    No need to poll for status
  </Card>

  <Card title="Better UX" icon="face-smile">
    Respond to events immediately
  </Card>

  <Card title="Scalable" icon="chart-line">
    Handle high volumes efficiently
  </Card>
</CardGroup>

## Workflow Overview

```mermaid theme={null}
sequenceDiagram
    participant Client as Your App
    participant API as JoggAI API
    participant Queue as Render Queue
    participant Webhook as Your Server
    
    Note over Client,Webhook: 1. Setup (One Time)
    Client->>API: POST /v2/endpoint
    API-->>Client: 200 OK {endpoint_id, secret}
    
    Note over Client,Webhook: 2. Create Video
    Client->>API: POST /v2/create_video_from_avatar
    API->>Queue: Queue task
    API-->>Client: 200 OK {video_id}
    
    Note over Queue: 3. Process (2-5 min)
    Queue->>Queue: Render video
    
    Note over Client,Webhook: 4. Notify
    Queue->>API: Complete
    API->>Webhook: POST /webhook (event, data, signature)
    Webhook->>Webhook: Verify & Process
    Webhook-->>API: 200 OK
```

<Info>
  Webhook requests expect a `200 OK` response within **5 seconds**. Non-2xx responses trigger automatic retries.
</Info>

## Quick Start

### Step 1: Add Webhook Endpoint

```bash theme={null}
curl --location --request POST 'https://api.jogg.ai/v2/endpoint' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "url": "https://example.com/webhook",
    "events": ["generated_avatar_video_success", "generated_avatar_video_failed"],
    "status": "enabled"
  }'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "endpoint_id": "wh_123456789",
    "url": "https://example.com/webhook",
    "secret": "whsec_abc123xyz",
    "status": "enabled",
    "events": ["generated_avatar_video_success", "generated_avatar_video_failed"],
    "username": "johndoe",
    "created_at": 1732806631
  }
}
```

<Check>
  Save the `secret` - you'll use it to verify webhook authenticity!
</Check>

### Step 2: Verify Webhook Signature

Always verify that webhooks come from JoggAI:

<AccordionGroup>
  <Accordion title="Go">
    ```go theme={null}
    func VerifyWebhookSignature(payload []byte, signature, secret string) bool {
        mac := hmac.New(sha256.New, []byte(secret))
        mac.Write(payload)
        expectedSignature := hex.EncodeToString(mac.Sum(nil))
        return hmac.Equal([]byte(signature), []byte(expectedSignature))
    }
    ```
  </Accordion>

  <Accordion title="Python">
    ```python theme={null}
    import hmac
    import hashlib

    def verify_webhook_signature(payload, signature, secret):
        expected = hmac.new(
            secret.encode('utf-8'),
            payload,
            hashlib.sha256
        ).hexdigest()
        return hmac.compare_digest(signature, expected)
    ```
  </Accordion>

  <Accordion title="Node.js">
    ```javascript theme={null}
    const crypto = require('crypto');

    function verifyWebhookSignature(payload, signature, secret) {
        const expected = crypto
            .createHmac('sha256', secret)
            .update(payload)
            .digest('hex');
        return crypto.timingSafeEqual(
            Buffer.from(signature),
            Buffer.from(expected)
        );
    }
    ```
  </Accordion>

  <Accordion title="Bash">
    ```bash theme={null}
    verify_webhook() {
      local payload="$1"
      local signature="$2"
      local secret="$3"
      
      expected=$(echo -n "$payload" | openssl dgst -sha256 -hmac "$secret" | awk '{print $2}')
      
      if [ "$signature" = "$expected" ]; then
        echo "✅ Signature verified"
        return 0
      else
        echo "❌ Invalid signature"
        return 1
      fi
    }
    ```
  </Accordion>
</AccordionGroup>

## Webhook Events

### Available Events

| Event                               | Description                         | When Triggered                             |
| ----------------------------------- | ----------------------------------- | ------------------------------------------ |
| `generated_video_success`           | Video generation succeeded          | Video is ready to download                 |
| `generated_video_failed`            | Video generation failed             | An error occurred during generation        |
| `generated_avatar_video_success`    | Avatar video generation succeeded   | Video is ready to download                 |
| `generated_avatar_video_failed`     | Avatar video generation failed      | An error occurred during generation        |
| `generated_product_video_success`   | Product video generation succeeded  | Video is ready to download                 |
| `generated_product_video_failed`    | Product video generation failed     | An error occurred during generation        |
| `generated_template_video_success`  | Template video generation succeeded | Video is ready to download                 |
| `generated_template_video_failed`   | Template video generation failed    | An error occurred during generation        |
| `generated_translate_video_success` | Video translation succeeded         | Translated video is ready                  |
| `generated_translate_video_failed`  | Video translation failed            | An error occurred during translation       |
| `create_avatar_success`             | Avatar creation succeeded           | Avatar is ready to use                     |
| `create_avatar_failed`              | Avatar creation failed              | An error occurred during avatar creation   |
| `generated_photo_avatar_success`    | Photo avatar creation succeeded     | Avatar is ready to use                     |
| `generated_photo_avatar_failed`     | Photo avatar creation failed        | An error occurred during avatar creation   |
| `generated_product_avatar_success`  | Product avatar creation succeeded   | Avatar is ready to use                     |
| `generated_product_avatar_failed`   | Product avatar creation failed      | An error occurred during avatar creation   |
| `generated_script_success`          | AI script generation succeeded      | Scripts are ready to use                   |
| `generated_script_failed`           | AI script generation failed         | An error occurred during script generation |
| `generated_image_success`           | Image generation succeeded          | Generated images are ready                 |
| `generated_image_failed`            | Image generation failed             | An error occurred during image generation  |
| `generated_motion_success`          | Motion generation succeeded         | Generated motion video is ready            |
| `generated_motion_failed`           | Motion generation failed            | An error occurred during motion generation |

<Tip>
  View [List Webhook Events](/api-reference/v2/Webhook/ListWebhookEvents) for the complete list of events.
</Tip>

### Event Payloads

<AccordionGroup>
  <Accordion title="Video Generation Success">
    ```json theme={null}
    {
      "event_id": "evt_123456789",
      "event": "generated_avatar_video_success",
      "timestamp": 1732806631,
      "data": {
        "video_id": "video_123456",
        "status": "completed",
        "video_url": "https://res.jogg.ai/video.mp4",
        "cover_url": "https://res.jogg.ai/cover.jpg",
        "duration": 30
      }
    }
    ```
  </Accordion>

  <Accordion title="Video Generation Failed">
    ```json theme={null}
    {
      "event_id": "evt_123456789",
      "event": "generated_avatar_video_failed",
      "timestamp": 1732806631,
      "data": {
        "video_id": "video_123456",
        "status": "failed",
        "error": {
          "code": 50000,
          "message": "Video generation failed"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Avatar Creation Success">
    ```json theme={null}
    {
      "event_id": "evt_987654321",
      "event": "generated_photo_avatar_success",
      "timestamp": 1732806631,
      "data": {
        "avatar_id": 123,
        "status": "completed",
        "preview_url": "https://res.jogg.ai/avatar-preview.mp4",
        "cover_url": "https://res.jogg.ai/avatar-cover.jpg"
      }
    }
    ```
  </Accordion>

  <Accordion title="Image Generation Success">
    ```json theme={null}
    {
      "event": "generated_image_success",
      "timestamp": 1732806631,
      "data": {
        "photo_id": "photo_123456",
        "photo_urls": [
          "https://res.jogg.ai/image1.jpg",
          "https://res.jogg.ai/image2.jpg"
        ]
      }
    }
    ```
  </Accordion>

  <Accordion title="Image Generation Failed">
    ```json theme={null}
    {
      "event": "generated_image_failed",
      "timestamp": 1732806631,
      "data": {
        "photo_id": "photo_123456",
        "error": "Image generation failed due to invalid parameters"
      }
    }
    ```
  </Accordion>

  <Accordion title="Motion Generation Success">
    ```json theme={null}
    {
      "event": "generated_motion_success",
      "timestamp": 1732806631,
      "data": {
        "motion_id": "motion_123456",
        "motion_url": "https://res.jogg.ai/motion.mp4",
        "photo_url": "https://res.jogg.ai/photo.jpg"
      }
    }
    ```
  </Accordion>

  <Accordion title="Motion Generation Failed">
    ```json theme={null}
    {
      "event": "generated_motion_failed",
      "timestamp": 1732806631,
      "data": {
        "motion_id": "motion_123456",
        "error": "Motion generation failed due to processing error"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Managing Webhooks

<AccordionGroup>
  <Accordion title="List All Webhooks">
    ```bash theme={null}
    curl --request GET 'https://api.jogg.ai/v2/endpoints' \
      --header 'x-api-key: YOUR_API_KEY'
    ```

    Response includes all configured webhook endpoints with their settings.

    See details: [List Webhook Endpoints](/api-reference/v2/Webhook/ListWebhookEndpoints)
  </Accordion>

  <Accordion title="Update Webhook">
    ```bash theme={null}
    curl --request PUT 'https://api.jogg.ai/v2/endpoint/wh_123456789' \
      --header 'x-api-key: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "url": "https://new-url.com/webhook",
        "events": ["generated_avatar_video_success", "generated_avatar_video_failed", "generated_photo_avatar_success"],
        "status": "enabled"
      }'
    ```

    Note: The `secret` cannot be modified.

    See details: [Update Webhook Endpoint](/api-reference/v2/Webhook/UpdateWebhookEndpoint)
  </Accordion>

  <Accordion title="Delete Webhook">
    ```bash theme={null}
    curl --request DELETE 'https://api.jogg.ai/v2/endpoint/wh_123456789' \
      --header 'x-api-key: YOUR_API_KEY'
    ```

    See details: [Delete Webhook Endpoint](/api-reference/v2/Webhook/DeleteWebhookEndpoint)
  </Accordion>

  <Accordion title="List Available Events">
    ```bash theme={null}
    curl --request GET 'https://api.jogg.ai/v2/events' \
      --header 'x-api-key: YOUR_API_KEY'
    ```

    Returns list of all supported webhook events.

    See details: [List Webhook Events](/api-reference/v2/Webhook/ListWebhookEvents)
  </Accordion>
</AccordionGroup>

## Security Requirements

### Request Headers

```bash theme={null}
POST /webhook HTTP/1.1
Host: your-domain.com
Content-Type: application/json
X-Webhook-Event: generated_avatar_video_success
X-Webhook-Signature: 7256c87be255861cbbe92f4a04a4500176b045a287f258e32e5b6c6b96d7f290
User-Agent: JoggAI-Webhook/2.0
```

### Security Checklist

* ✅ All webhook URLs must use HTTPS
* ✅ Verify `X-Webhook-Signature` header on every request
* ✅ Use HMAC SHA-256 with your secret key
* ✅ Signature is computed on raw request body
* ✅ Use constant-time comparison to prevent timing attacks
* ✅ Keep webhook secret secure (environment variables)
* ✅ Rotate secrets periodically

<Warning>
  Always verify signatures before processing webhooks. Reject requests with invalid signatures and log suspicious attempts.
</Warning>

## Related Documentation

<CardGroup>
  <Card title="Create Avatar Videos" icon="user" href="/api-reference/v2/API Documentation/CreateAvatarVideos">
    Set up video creation with webhooks
  </Card>

  <Card title="Product Video Workflow" icon="shopping-bag" href="/api-reference/v2/API Documentation/URLtoVideo">
    Use webhooks for product videos
  </Card>

  <Card title="Webhook API Reference" icon="code" href="/api-reference/v2/Webhook/ListWebhookEndpoints">
    Detailed webhook API documentation
  </Card>
</CardGroup>


# Create AI Script
Source: https://docs.jogg.ai/api-reference/v2/Asset/CreateAIScript

POST /v2/ai_scripts
Generate AI-powered video script based on product information and requirements.
The script generation is asynchronous - use the returned task_id to check status.


Generate AI-powered video scripts based on product information. The AI will create multiple script variations optimized for your video duration.

## Example Usage

### Using Product ID

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/ai_scripts' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "language": "english",
    "video_length_seconds": "30",
    "script_style": "Storytime",
    "product_info": {
      "source_type": "id",
      "data": {
        "id": "NTQ0MTkzNjg"
      }
    }
  }'
```

### Using Product Details

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/ai_scripts' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "language": "english",
    "video_length_seconds": "30",
    "script_style": "Discovery",
    "product_info": {
      "source_type": "details",
      "data": {
    "name": "Amazing Smart Watch",
        "description": "A smartwatch with health tracking, fitness monitoring, and smart notifications"
      }
    },
    "target_audience": "Fitness enthusiasts and tech-savvy consumers"
  }'
```

## Related Guides

<CardGroup>
  <Card title="AI Scripts Guide" href="/api-reference/v2/API Documentation/AIScripts">
    Learn the complete AI scripts workflow
  </Card>

  <Card title="Get Script Results" href="/api-reference/v2/Asset/GetAIScriptResult">
    Retrieve generated scripts
  </Card>
</CardGroup>


# Get AI Script Result
Source: https://docs.jogg.ai/api-reference/v2/Asset/GetAIScriptResult

GET /v2/ai_scripts/results/{task_id}
Check the status and retrieve results of AI script generation task.
Scripts are generated in multiple styles for variety.


Retrieve the generated AI scripts by task ID.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/ai_scripts/results/task_abc123' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Related Guides

<CardGroup>
  <Card title="AI Scripts Guide" href="/api-reference/v2/API Documentation/AIScripts">
    Learn about AI script generation
  </Card>
</CardGroup>


# Get Background Music
Source: https://docs.jogg.ai/api-reference/v2/Asset/GetMusic

GET /v2/musics
Get available background music with pagination.
Supports filtering and sorting of music tracks.


Browse JoggAI's library of royalty-free background music.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/musics' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Query Parameters

* `genre` - Filter by genre (e.g., "Corporate", "Ambient")
* `mood` - Filter by mood (e.g., "Energetic", "Calm")


# Get Visual Styles
Source: https://docs.jogg.ai/api-reference/v2/Asset/GetVisualStyles

GET /v2/visual_styles
Get available visual styles/templates filtered by aspect ratio.
Visual styles determine the look and feel of your product videos.


Retrieve available visual styles for video creation.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/visual_styles' \
  --header 'x-api-key: YOUR_API_KEY'
```


# Upload Asset
Source: https://docs.jogg.ai/api-reference/v2/Asset/UploadAsset

POST /v2/upload/asset
Upload an asset file and get signed URL for direct upload to cloud storage.
Use the returned sign_url to upload your file with a PUT request.


Upload custom images, videos, or audio files to use in your video projects.

## Example Usage

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/upload/asset' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=@/path/to/your/image.jpg' \
  --form 'asset_type=image' \
  --form 'name=Product Photo'
```

## Related Guides

<CardGroup>
  <Card title="Upload Media Guide" href="/api-reference/v2/API Documentation/UploadMedia">
    Learn about media uploads
  </Card>
</CardGroup>


# Get Custom Avatars
Source: https://docs.jogg.ai/api-reference/v2/Avatar/CustomAvatarsGet

GET /v2/avatars/custom
Retrieve list of user's instant avatars.
Returns user's custom instant avatar collection with filtering options.


Retrieve the list of your custom avatars including photo avatars and product avatars.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/avatars/custom' \
  --header 'x-api-key: YOUR_API_KEY'
```


# Check Motion Status
Source: https://docs.jogg.ai/api-reference/v2/Avatar/MotionStatusCheck

GET /v2/photo_avatar
Check the status of motion generation task by motion ID

Check the status of motion generation task by motion ID.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/photo_avatar?motion_id=motion_123' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Related Guides

<CardGroup>
  <Card title="Add Motion to Photo Avatar" href="/api-reference/v2/Avatar/PhotoAvatarMotionAdd">
    Add motion to photo avatar
  </Card>

  <Card title="Generate Photo Avatar" href="/api-reference/v2/Avatar/PhotoAvatarGenerate">
    Generate photo avatar first
  </Card>
</CardGroup>


# Generate Photo Avatar
Source: https://docs.jogg.ai/api-reference/v2/Avatar/PhotoAvatarGenerate

POST /v2/photo_avatar/photo/generate
Generate AI photo avatar based on provided parameters

Generate a custom AI avatar from a photo. Upload a portrait photo to create a talking avatar.

## Example Usage

```bash theme={null}
curl -X POST 'https://api.jogg.ai/v2/photo_avatar/photo/generate' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "photo_url": "https://example.com/portrait.jpg",
    "name": "John Doe Avatar"
  }'
```

## Related Guides

<CardGroup>
  <Card title="Create Photo Avatar Guide" href="/api-reference/v2/API Documentation/CreatePhotoAvatar">
    Complete photo avatar workflow
  </Card>
</CardGroup>


# Add Motion to Photo Avatar
Source: https://docs.jogg.ai/api-reference/v2/Avatar/PhotoAvatarMotionAdd

POST /v2/photo_avatar/add_motion
Add motion to a photo avatar to make it animated

Add motion to a photo avatar to make it animated.

## Example Usage

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/photo_avatar/add_motion' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "image_url": "https://res.jogg.ai/photo.jpg",
    "name": "My Photo Avatar",
    "voice_id": "en-US-ChristopherNeural",
    "model": "2.0"
  }'
```

## Related Guides

<CardGroup>
  <Card title="Generate Photo Avatar" href="/api-reference/v2/Avatar/PhotoAvatarGenerate">
    Generate photo avatar first
  </Card>

  <Card title="Check Motion Status" href="/api-reference/v2/Avatar/MotionStatusCheck">
    Check motion generation status
  </Card>
</CardGroup>


# Get Photo Avatar Status
Source: https://docs.jogg.ai/api-reference/v2/Avatar/PhotoAvatarStatusGet

GET /v2/photo_avatar/photo
Check the status of photo avatar generation task by photo ID

Check the status of photo avatar generation task by photo ID.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/photo_avatar/photo?photo_id=photo_123' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Related Guides

<CardGroup>
  <Card title="Generate Photo Avatar" href="/api-reference/v2/Avatar/PhotoAvatarGenerate">
    Generate photo avatar
  </Card>

  <Card title="Add Motion" href="/api-reference/v2/Avatar/PhotoAvatarMotionAdd">
    Add motion to photo avatar
  </Card>
</CardGroup>


# Get Photo Avatars
Source: https://docs.jogg.ai/api-reference/v2/Avatar/PhotoAvatarsGet

GET /v2/avatars/photo_avatars
Retrieve list of user's photo avatars.
Returns user's photo-based avatar collection with filtering options.


Retrieve the list of your photo avatars created from uploaded photos.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/avatars/photo_avatars' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Related Guides

<CardGroup>
  <Card title="Create Photo Avatar Guide" href="/api-reference/v2/API Documentation/CreatePhotoAvatar">
    Learn how to create photo avatars
  </Card>
</CardGroup>


# Get Public Avatars
Source: https://docs.jogg.ai/api-reference/v2/Avatar/PublicAvatarsGet

GET /v2/avatars/public
Retrieve list of public avatars with filtering options.
Supports pagination and various filters including aspect ratio, style, gender, age, scene, and ethnicity.


Retrieve the list of public avatars available from the JoggAI library. These avatars can be used immediately in your videos.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/avatars/public' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Related Guides

<CardGroup>
  <Card title="Create Avatar Videos" href="/api-reference/v2/API Documentation/CreateAvatarVideos">
    Use avatars to create videos
  </Card>
</CardGroup>


# Create Product
Source: https://docs.jogg.ai/api-reference/v2/Product/CreateProduct

POST /v2/product
Create a new product with URL analysis or manual input.
This is Step 1 in the product video generation workflow.


Create a product entry from a URL or manual product information. The system will extract product details automatically.

## Example Usage

```bash theme={null}
curl -X POST 'https://api.jogg.ai/v2/product' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/product/amazing-gadget"
  }'
```

## Related Guides

<CardGroup>
  <Card title="URL to Video Guide" href="/api-reference/v2/API Documentation/URLtoVideo">
    Complete product video workflow
  </Card>
</CardGroup>


# Update Product
Source: https://docs.jogg.ai/api-reference/v2/Product/UpdateProduct

PUT /v2/product
Update an existing product information (Step 2 - Optional)

Update an existing product's information including name, description, target audience, and media resources.

This is an optional step in the product video workflow, allowing you to refine product details before generating videos.

## Example Usage

```bash theme={null}
curl -X PUT 'https://api.jogg.ai/v2/product' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "product_id": "NTQ0MTkzNjg",
    "name": "Updated Product Name",
    "description": "Updated product description and selling points",
    "target_audience": "Updated target audience"
  }'
```

## Related Guides

<CardGroup>
  <Card title="URL to Video Guide" href="/api-reference/v2/API Documentation/URLtoVideo">
    Complete product video workflow
  </Card>

  <Card title="Create Product" href="/api-reference/v2/Product/CreateProduct">
    Create a new product
  </Card>
</CardGroup>


# Error Handling
Source: https://docs.jogg.ai/api-reference/v2/QuickStart/ErrorHandling

API error codes and responses

## Response Structure

All API responses follow this structure:

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {...}
}
```

* `code: 0` = Success
* `code > 0` = Error

***

## Error Codes

| Code      | Message                    | Description                              |
| --------- | -------------------------- | ---------------------------------------- |
| **0**     | Success                    | Request completed successfully           |
| **429**   | Rate limit exceeded        | Too many POST requests (20/minute limit) |
| **10104** | Record not found           | Resource ID does not exist               |
| **10105** | Invalid API key            | Wrong or missing `x-api-key` header      |
| **18020** | Insufficient credit        | Not enough credits to complete request   |
| **18025** | No permission to call APIs | Account lacks API access permission      |
| **40000** | Parameter error            | Invalid or missing required parameters   |
| **50000** | System error               | Internal server error                    |

***

## Error Response Examples

### Authentication Error

```json theme={null}
{
  "code": 10105,
  "msg": "Invalid API key",
  "data": null
}
```

### Insufficient Credits

```json theme={null}
{
  "code": 18020,
  "msg": "Insufficient credit",
  "data": null
}
```

### Parameter Error

```json theme={null}
{
  "code": 40000,
  "msg": "Parameter error: avatar_id is required",
  "data": null
}
```

### Rate Limit Error

```json theme={null}
{
  "code": 429,
  "msg": "Rate limit exceeded. Please try again later.",
  "data": null
}
```

***

## Best Practices

<CardGroup>
  <Card title="Check Response Code" icon="check">
    Always verify the `code` field before processing data
  </Card>

  <Card title="Handle Errors" icon="triangle-exclamation">
    Implement proper error handling for all error codes
  </Card>

  <Card title="Log Errors" icon="file-lines">
    Record error details with timestamps for debugging
  </Card>

  <Card title="Retry Logic" icon="rotate">
    Implement retry for system errors (50000) and rate limits (429)
  </Card>
</CardGroup>

***

## Need Help?

Contact [support@jogg.ai](mailto:support@jogg.ai) with:

* Error code and message
* Request parameters
* Timestamp
* API endpoint

<Note>
  Include your user ID (not your API key) when contacting support.
</Note>


# Getting Started
Source: https://docs.jogg.ai/api-reference/v2/QuickStart/GettingStarted

Quick start guide for JoggAI API

## Welcome to JoggAI API

The JoggAI API unlocks new possibilities, enabling you to effortlessly create dynamic avatar videos and seamlessly integrate JoggAI's advanced AI features into your product.

<CardGroup>
  <Card title="Create Account" icon="user-plus" href="#create-account">
    Sign up and get your API key
  </Card>

  <Card title="Pricing" icon="dollar-sign" href="/api-reference/v2/QuickStart/Pricing">
    View credit pricing
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/api-reference/v2/QuickStart/ErrorHandling">
    Understand error codes
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/api-reference/v2/QuickStart/RateLimits">
    Manage API usage
  </Card>
</CardGroup>

***

## Create Account

Sign up to create an account at [https://app.jogg.ai/register](https://app.jogg.ai/register) to access JoggAI's API capabilities.

***

### Get Your API Key

<Steps>
  <Step title="Sign In">
    Log in to [JoggAI](https://app.jogg.ai/login)
  </Step>

  <Step title="Navigate to API Settings">
    Click your avatar → Select "API" from the menu

    <img alt="" />
  </Step>

  <Step title="Copy Your Key">
    Copy your API key and store it securely

    <img alt="" />

    <Warning>
      **Keep your API key secure!** Never expose it in client-side code or public repositories.
    </Warning>
  </Step>
</Steps>

### Test Your API Key

Include your API key in the request header:

```bash theme={null}
curl -X GET 'https://api.jogg.ai/v2/user/whoami' \
  -H 'x-api-key: YOUR_API_KEY'
```

**Expected Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "email": "user@example.com",
    "username": "johndoe"
  }
}
```

***

## Quick Start Example

Here's a simple example to create an avatar video:

```bash theme={null}
  curl -X POST  https://api.jogg.ai/v2/create_video_from_avatar \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
      "avatar": {
        "avatar_type": "0",
        "avatar_id": 412
      },
      "voice": {
        "type": "script",
        "voice_id": "MFZUKuGQUsGJPQjTS4wC",
        "script": "测试一下"
      },
      "aspect_ratio": "portrait",
      "screen_style": 1,
      "caption": true,
      "webhook_url": "your_webhook_url",
      "video_name": "My Talking Avatar Video"
    }'
```

<Tip>
  See our \[Workflows Guides]\(/api-reference/v2/API Documentation/CreateAvatarVideos) for detailed examples and use cases.
</Tip>

***

## Need Help?

For questions or issues:

* **Email:** [support@jogg.ai](mailto:support@jogg.ai)
* **Dashboard:** [app.jogg.ai](https://app.jogg.ai)
* **Documentation:** Explore our workflow guides for detailed examples

<Note>
  Include your user ID (not API key) when contacting support.
</Note>

Looking for legacy API documentation? Click [here](/api-reference/v1/QuickStart/GettingStarted).


# Pricing
Source: https://docs.jogg.ai/api-reference/v2/QuickStart/Pricing

API credit consumption and pricing

## API Credit Consumption

JoggAI API uses a credit-based pricing model. Credits are consumed based on the type of operation and resource usage.

***

## Credit Pricing Table

| Service                             | Consumption                | Details                                                                                   |
| ----------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------- |
| **Video Generation**                | 1 credit per 2 minutes     | Videos less than 2 minutes also consume 1 credit                                          |
| **Video Translation**               | 0.5 credits per 20 seconds | Videos less than 20 seconds also consume 0.5 credits                                      |
| **Lip Sync Video**                  | 1 credit per 125 seconds   | Estimated at about 0.008 credit per second, typically displayed as 0.01 credit per second |
| **Preview Video**                   | 0.5 credits per 2 minutes  | Videos less than 2 minutes also consume 0.5 credits                                       |
| **AI Scripts**                      | 0.2 credits per call       | Per API request                                                                           |
| **Photo Avatar Generation**         | 0.05 credits per image     | Single image generation                                                                   |
| **Photo Avatar Generation (Batch)** | 0.2 credits per call       | Generates 4 images                                                                        |
| **Motion 1.0**                      | 2 credits                  | Per motion generation                                                                     |
| **Motion 2.0**                      | 2 credits                  | Per motion generation                                                                     |
| **Motion 2.0 Pro**                  | 3 credits                  | Per motion generation                                                                     |
| **Motion 3.0**                      | 2 credits                  | Per motion generation                                                                     |

***

## Pricing Examples

<AccordionGroup>
  <Accordion title="Video Generation Examples">
    * **30 seconds video:** 1 credit
    * **1 minute video:** 1 credit
    * **2 minutes video:** 1 credit
    * **3 minutes video:** 2 credits
    * **5 minutes video:** 3 credits
  </Accordion>

  <Accordion title="Preview Video Examples">
    * **30 seconds preview:** 0.5 credit
    * **1 minute preview:** 0.5 credit
    * **2 minutes preview:** 0.5 credit
    * **3 minutes preview:** 1 credit
  </Accordion>

  <Accordion title="Lip Sync Video Examples">
    * **30 seconds lip sync:** about 0.24 credit
    * **60 seconds lip sync:** about 0.48 credit
    * **125 seconds lip sync:** 1 credit
    * **250 seconds lip sync:** 2 credits
  </Accordion>

  <Accordion title="Image Generation Examples">
    * **Single image:** 0.05 credit
    * **Batch (4 images):** 0.2 credit
    * **10 single images:** 0.5 credit
  </Accordion>
</AccordionGroup>

***

## Check Your Balance

You can check your remaining credits via:

* **Dashboard:** Visit [app.jogg.ai](https://app.jogg.ai)
* **API:** Use the [Get User Info](/api-reference/v2/User/GetUserInfo) endpoint
* **API:** Use the [Get Remaining Quota](/api-reference/v2/User/GetRemainingQuota) endpoint

<Note>
  Credits are deducted immediately when a request is processed, not when it completes.
</Note>

***

## Need More Credits?

For enterprise pricing or volume discounts, contact [support@jogg.ai](mailto:support@jogg.ai).


# Rate Limits
Source: https://docs.jogg.ai/api-reference/v2/QuickStart/RateLimits

API rate limits and usage quotas

## Overview

To ensure fair usage and service quality, the API implements rate limits based on your API key.

<Info>
  **Current Limit:** 20 POST requests per minute per API key
</Info>

***

## Rate Limit Rules

| Rule            | Value                       |
| --------------- | --------------------------- |
| **Limit**       | 20 POST requests per minute |
| **Time Window** | 60 seconds (1 minute)       |

***

## Error Response

When you exceed 20 POST requests per minute:

```json theme={null}
{
  "code": 429,
  "msg": "Rate limit exceeded. Please try again later.",
  "data": null
}
```

**What to do:**

* Wait for the time specified in `retryAfter` (seconds)
* Reduce POST request frequency

***

## Best Practices

<CardGroup>
  <Card title="Use Webhooks" icon="webhook">
    Use webhooks instead of polling for status updates
  </Card>

  <Card title="Monitor Headers" icon="chart-line">
    Check X-RateLimit-Remaining to avoid hitting limits
  </Card>

  <Card title="Queue Requests" icon="list">
    Spread POST requests over time
  </Card>

  <Card title="Use GET for Status" icon="eye">
    GET requests are not limited - use them for checking status
  </Card>
</CardGroup>

***

## Need Help?

If you're experiencing rate limit issues, contact [support@jogg.ai](mailto:support@jogg.ai).


# Get Template by ID
Source: https://docs.jogg.ai/api-reference/v2/Template/GetTemplateById

GET /v2/template/custom/{id}
Retrieve detailed information about a specific custom template including its variables.


Retrieve details of a specific template by its ID.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/template/custom/tmpl_123' \
  --header 'x-api-key: YOUR_API_KEY'
```


# Get Templates
Source: https://docs.jogg.ai/api-reference/v2/Template/GetTemplates

GET /v2/templates/custom
Retrieve a list of user's custom templates with optional filtering by aspect ratio.


Retrieve the list of available video templates.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/templates/custom' \
  --header 'x-api-key: YOUR_API_KEY'
```


# Get Remaining Quota
Source: https://docs.jogg.ai/api-reference/v2/User/GetRemainingQuota

GET /v2/user/remaining_quota
Retrieve the remaining JoggAI API quota for the authenticated user

Check your remaining API quota and credits.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/user/remaining_quota' \
  --header 'x-api-key: YOUR_API_KEY'
```

**Response:**

```json theme={null}
{
  "code": 0,
  "msg": "Success",
  "data": {
    "remaining_quota": 1000.0
  }
}
```


# Get User Info
Source: https://docs.jogg.ai/api-reference/v2/User/GetUserInfo

GET /v2/user/whoami
Easily retrieve and manage your account details with JoggAI API

Retrieve authenticated user information including email and credits.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/user/whoami' \
  --header 'x-api-key: YOUR_API_KEY'
```


# Get Avatar Video Status
Source: https://docs.jogg.ai/api-reference/v2/Video/AvatarVideoGet

GET /v2/avatar_video/{id}
Get video information and status by video ID

Retrieve the status and details of an avatar video by its project ID. Use this endpoint to check if video generation is complete and get the video URL.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/avatar_video/vid_abc123' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Related Guides

<CardGroup>
  <Card title="Create Avatar Videos Guide" href="/api-reference/v2/API Documentation/CreateAvatarVideos">
    Learn how to create avatar videos
  </Card>
</CardGroup>


# Create Lip Sync Video Task
Source: https://docs.jogg.ai/api-reference/v2/Video/CreateLipSyncVideo

POST /v2/create_lip_sync_video
Submit a video URL and an audio URL to create a lip sync task.
Use the returned task ID to poll for processing status and results.


Submit a source video URL and a source audio URL to create a lip sync video task.

## Example Usage

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_lip_sync_video' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "video_url": "https://res.jogg.ai/source-video.mp4",
    "audio_url": "https://res.jogg.ai/source-audio.wav",
    "playback_type": "normal"
  }'
```

## Related Guides

<CardGroup>
  <Card title="Get Lip Sync Task Status" href="/api-reference/v2/Video/GetLipSyncVideo">
    Check task processing status and results
  </Card>
</CardGroup>


# Create Video from Avatar
Source: https://docs.jogg.ai/api-reference/v2/Video/CreateVideoFromAvatar

POST /v2/create_video_from_avatar
Create a video with talking avatar using script or audio input.
Either provide a script for text-to-speech or upload an audio file.


Create a talking avatar video by providing a script, avatar ID, and voice ID. This endpoint generates videos with AI avatars speaking your provided text.

## Example Usage

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_from_avatar' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "script": "Welcome to JoggAI! Create amazing avatar videos with our API.",
    "avatar_id": 127,
    "voice_id": "en-US-ChristopherNeural",
    "aspect_ratio": 0,
    "screen_style": 0
  }'
```

## Related Guides

<CardGroup>
  <Card title="Create Avatar Videos Guide" href="/api-reference/v2/API Documentation/CreateAvatarVideos">
    Learn how to create avatar videos step-by-step
  </Card>

  <Card title="Get Video Status" href="/api-reference/v2/Video/AvatarVideoGet">
    Check the status of your video generation
  </Card>
</CardGroup>


# Create Video from Product
Source: https://docs.jogg.ai/api-reference/v2/Video/CreateVideoFromProduct

POST /v2/create_video_from_product
Create a video from product information with customizable visual style, avatar, voice, and script.
This is the final step after creating a product to generate the actual video.


Generate a product marketing video from product information. This endpoint creates videos with AI-generated scripts based on your product details.

## Example Usage

```bash theme={null}
curl -X POST 'https://api.jogg.ai/v2/create_video_from_product' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "product_id": "prod_abc123",
    "avatar_id": 127,
    "voice_id": "en-US-ChristopherNeural",
    "aspect_ratio": 1
  }'
```

## Related Guides

<CardGroup>
  <Card title="URL to Video Guide" href="/api-reference/v2/API Documentation/URLtoVideo">
    Learn the complete product video workflow
  </Card>

  <Card title="Create Product" href="/api-reference/v2/Product/CreateProduct">
    First create a product from URL
  </Card>
</CardGroup>


# Create Video with Template
Source: https://docs.jogg.ai/api-reference/v2/Video/CreateVideoWithTemplate

POST /v2/create_video_with_template
Create a video using a template with custom variables and settings.
Templates support various variable types including text, image, video, and script.


Create a video using a pre-designed template. Templates provide consistent branding and faster video creation.

## Example Usage

### Basic Example with Text and Script Variables

```bash theme={null}
curl -X POST 'https://api.jogg.ai/v2/create_video_with_template' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "template_id": 1234,
    "video_name": "Product Showcase",
    "avatar_id": 127,
    "avatar_type": 0,
    "voice_language": "english",
    "voice_id": "en-US-ChristopherNeural",
    "variables": [
      {
        "type": "text",
        "name": "product_name",
        "properties": {
          "content": "Amazing Smart Watch"
        }
      },
      {
        "type": "script",
        "name": "script",
        "properties": {
          "content": "Check out our amazing product!"
        }
      }
    ]
  }'
```

### Example with Image Variable (URL)

```bash theme={null}
curl -X POST 'https://api.jogg.ai/v2/create_video_with_template' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "template_id": 1234,
    "voice_language": "english",
    "variables": [
      {
        "type": "image",
        "name": "product_image",
        "properties": {
          "url": "https://example.com/product.jpg"
        }
      },
      {
        "type": "script",
        "name": "script",
        "properties": {
          "content": "Check out this amazing product!"
        }
      }
    ]
  }'
```

### Example with Image Variable (Asset ID)

```bash theme={null}
curl -X POST 'https://api.jogg.ai/v2/create_video_with_template' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "template_id": 1234,
    "voice_language": "english",
    "variables": [
      {
        "type": "image",
        "name": "product_image",
        "properties": {
          "asset_id": 5678
        }
      },
      {
        "type": "script",
        "name": "script",
        "properties": {
          "content": "Check out this amazing product!"
        }
      }
    ]
  }'
```

## Variable Properties

| Property   | Type    | Description                                                                                          |
| ---------- | ------- | ---------------------------------------------------------------------------------------------------- |
| `content`  | string  | For text/script type: Required, the text content. For image/video type: Optional, can be used as URL |
| `url`      | string  | Media resource URL for image/video type (choose url or asset\_id)                                    |
| `asset_id` | integer | Asset ID for image/video type, obtained from /v2/upload/asset (choose url or asset\_id)              |

## Related Guides

<CardGroup>
  <Card title="Get Templates" href="/api-reference/v2/Template/GetTemplates">
    Browse available templates
  </Card>

  <Card title="Upload Media" href="/api-reference/v2/API Documentation/UploadMedia">
    Upload assets to get asset\_id
  </Card>
</CardGroup>


# Get Lip Sync Video Task
Source: https://docs.jogg.ai/api-reference/v2/Video/GetLipSyncVideo

GET /v2/lip_sync_video/{task_id}
Query lip sync task status and result by task ID.


Query the status and result of a lip sync video task by `task_id`.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/lip_sync_video/3d5c6930-d0da-4f7b-826e-cd1530f6734f' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Related Guides

<CardGroup>
  <Card title="Create Lip Sync Video Task" href="/api-reference/v2/Video/CreateLipSyncVideo">
    Submit a new lip sync task
  </Card>
</CardGroup>


# Get Product Video Status
Source: https://docs.jogg.ai/api-reference/v2/Video/ProductVideoGet

GET /v2/product_video/{product_video_id}
Get the current status and details of a product video generation

Retrieve the status and details of a product video by its ID.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/product_video/vid_abc123' \
  --header 'x-api-key: YOUR_API_KEY'
```


# Render Video from Preview
Source: https://docs.jogg.ai/api-reference/v2/Video/RenderSinglePreview

POST /v2/create_video_from_product/render_single_preview
Generate final video from a selected preview

Generate final video from a selected preview.

## Example Usage

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_from_product/render_single_preview' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "preview_id": "preview_123"
  }'
```

## Related Guides

<CardGroup>
  <Card title="Submit Preview List" href="/api-reference/v2/Video/SubmitPreviewList">
    Generate multiple previews
  </Card>

  <Card title="Product Videos" href="/api-reference/v2/API Documentation/URLtoVideo">
    Complete product video workflow
  </Card>
</CardGroup>


# Submit Preview List
Source: https://docs.jogg.ai/api-reference/v2/Video/SubmitPreviewList

POST /v2/create_video_from_product/preview_list
Submit multiple visual styles for preview generation from a product.
This allows you to generate multiple preview videos with different styles simultaneously.


Submit multiple visual styles for preview generation from a product. This allows you to generate multiple preview videos with different styles simultaneously.

## Example Usage

```bash theme={null}
curl --request POST \
  --url 'https://api.jogg.ai/v2/create_video_from_product/preview_list' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "product_id": "NTIzMzc0NjI5",
    "visual_styles": ["Simple Product Switch", "Dynamic Showcase"],
    "video_spec": {
      "aspect_ratio": "landscape",
      "length": "30",
      "caption": true
    },
    "avatar": {
      "id": 1,
      "type": 0
    },
    "voice": {
      "id": "en-US-ChristopherNeural"
    },
    "audio": {},
    "script": {
      "style": "Storytime",
      "language": "english"
    }
  }'
```

## Related Guides

<CardGroup>
  <Card title="Product Videos" href="/api-reference/v2/API Documentation/URLtoVideo">
    Complete product video workflow
  </Card>

  <Card title="Render Preview" href="/api-reference/v2/Video/RenderSinglePreview">
    Render final video from preview
  </Card>
</CardGroup>


# Get Template Video
Source: https://docs.jogg.ai/api-reference/v2/Video/TemplateVideoGet

GET /v2/template_video/{video_id}
Retrieve video information, status, and metadata by video ID

Retrieve video information, status, and metadata by video ID.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/template_video/video_123456789' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Related Guides

<CardGroup>
  <Card title="Create Video from Template" href="/api-reference/v2/Video/CreateVideoWithTemplate">
    Create videos from templates
  </Card>

  <Card title="Create Video from Template" href="/api-reference/v2/API Documentation/CreateVideoFromTemplate">
    Complete template video guide
  </Card>
</CardGroup>


# Translate Video
Source: https://docs.jogg.ai/api-reference/v2/Video/VideoTranslateCreate

POST /v2/video_translate/
Create a video translation task with specified parameters including target language, voice, and subtitle options.


Translate an existing video into another language with voiceover and subtitles.

<Warning>
  **Video Duration Limit:** Videos must be between **0-3 minutes** in length.
</Warning>

## Example Usage

```bash theme={null}
curl -X POST 'https://api.jogg.ai/v2/video_translate/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "video_url": "https://example.com/original.mp4",
    "target_language": "es",
    "voice_id": "es-ES-AlvaroNeural",
    "enable_subtitles": true
  }'
```

## Related Guides

<CardGroup>
  <Card title="Video Translation Guide" href="/api-reference/v2/API Documentation/VideoTranslation">
    Learn about video translation workflow
  </Card>

  <Card title="Get Target Languages" href="/api-reference/v2/Video/VideoTranslateTargetLanguagesList">
    See supported languages
  </Card>
</CardGroup>


# Check Translation Status
Source: https://docs.jogg.ai/api-reference/v2/Video/VideoTranslateGet

GET /v2/video_translate/{video_translate_id}
Get the current status and details of a video translation task

Get the current status and details of a video translation task.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/video_translate/vt_123456' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Related Guides

<CardGroup>
  <Card title="Translate Video" href="/api-reference/v2/Video/VideoTranslateCreate">
    Translate videos
  </Card>

  <Card title="Video Translation Guide" href="/api-reference/v2/API Documentation/VideoTranslation">
    Complete translation workflow
  </Card>
</CardGroup>


# Get Target Languages
Source: https://docs.jogg.ai/api-reference/v2/Video/VideoTranslateTargetLanguagesList

GET /v2/video_translate/target_languages
Get the list of supported target languages for video translation

Get the list of supported languages for video translation.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/video_translate/target_languages' \
  --header 'x-api-key: YOUR_API_KEY'
```


# Get Custom Voices
Source: https://docs.jogg.ai/api-reference/v2/Voice/GetCustomVoices

GET /v2/voices/custom
Retrieve a list of user's custom timbres with filtering options.
Returns user's personalized voice collection.


Retrieve the list of your custom cloned voices.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/voices/custom' \
  --header 'x-api-key: YOUR_API_KEY'
```


# Get Voices
Source: https://docs.jogg.ai/api-reference/v2/Voice/GetVoices

GET /v2/voices
Retrieve a list of available timbres with filtering options.
Supports pagination and various filters including gender, language, age, and use case.


Retrieve the list of available voices for text-to-speech. JoggAI offers natural-sounding voices in 40+ languages.

## Example Usage

```bash theme={null}
curl --request GET \
  --url 'https://api.jogg.ai/v2/voices' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Query Parameters

* `language` - Filter by language code (e.g., "en-US")
* `gender` - Filter by gender ("Male" or "Female")


# Add Webhook Endpoint
Source: https://docs.jogg.ai/api-reference/v2/Webhook/AddWebhookEndpoint

POST /v2/endpoint
Create a new webhook endpoint to receive event notifications.
You can specify which events to subscribe to and configure the endpoint URL.


Create a new webhook endpoint to receive event notifications.

You can specify which event types to subscribe to and configure the endpoint URL.

<Info>
  **Limit**: Each user can create up to **20** webhook endpoints.
</Info>

## Use Cases

* Receive video generation completion notifications
* Monitor task failure events
* Track avatar creation status in real-time
* Integrate with third-party systems

## Important Notes

<Note>
  Webhook endpoints must be able to receive POST requests and return a 2xx status code within **5 seconds** to confirm receipt.
</Note>

<Warning>
  Ensure your endpoint URL is a publicly accessible **HTTPS** address.
</Warning>

## Available Event Types

### Video Generation Events

| Event                               | Description                         | When Triggered                       |
| ----------------------------------- | ----------------------------------- | ------------------------------------ |
| `generated_video_success`           | Video generation succeeded          | Video is ready to download           |
| `generated_video_failed`            | Video generation failed             | An error occurred during generation  |
| `generated_product_video_success`   | Product video generation succeeded  | Video is ready to download           |
| `generated_product_video_failed`    | Product video generation failed     | An error occurred during generation  |
| `generated_avatar_video_success`    | Avatar video generation succeeded   | Video is ready to download           |
| `generated_avatar_video_failed`     | Avatar video generation failed      | An error occurred during generation  |
| `generated_template_video_success`  | Template video generation succeeded | Video is ready to download           |
| `generated_template_video_failed`   | Template video generation failed    | An error occurred during generation  |
| `generated_translate_video_success` | Video translation succeeded         | Translated video is ready            |
| `generated_translate_video_failed`  | Video translation failed            | An error occurred during translation |

### Avatar Generation Events

| Event                              | Description                       | When Triggered                           |
| ---------------------------------- | --------------------------------- | ---------------------------------------- |
| `create_avatar_success`            | Avatar creation succeeded         | Avatar is ready to use                   |
| `create_avatar_failed`             | Avatar creation failed            | An error occurred during avatar creation |
| `generated_photo_avatar_success`   | Photo avatar creation succeeded   | Avatar is ready to use                   |
| `generated_photo_avatar_failed`    | Photo avatar creation failed      | An error occurred during avatar creation |
| `generated_product_avatar_success` | Product avatar creation succeeded | Avatar is ready to use                   |
| `generated_product_avatar_failed`  | Product avatar creation failed    | An error occurred during avatar creation |

### AI Script Generation Events

| Event                      | Description                    | When Triggered                             |
| -------------------------- | ------------------------------ | ------------------------------------------ |
| `generated_script_success` | AI script generation succeeded | Scripts are ready to use                   |
| `generated_script_failed`  | AI script generation failed    | An error occurred during script generation |

### Image Generation Events

| Event                     | Description                | When Triggered                            |
| ------------------------- | -------------------------- | ----------------------------------------- |
| `generated_image_success` | Image generation succeeded | Generated images are ready                |
| `generated_image_failed`  | Image generation failed    | An error occurred during image generation |

### Motion Generation Events

| Event                      | Description                 | When Triggered                             |
| -------------------------- | --------------------------- | ------------------------------------------ |
| `generated_motion_success` | Motion generation succeeded | Generated motion video is ready            |
| `generated_motion_failed`  | Motion generation failed    | An error occurred during motion generation |

<Tip>
  Use the [List Webhook Events](/api-reference/v2/Webhook/ListWebhookEvents) endpoint to get all available event types.
</Tip>

## Webhook Signature Verification

Each webhook request includes a signature to verify the authenticity of the request source. Use the returned `secret` to verify the signature.

### Example Request Headers

```http theme={null}
POST /webhook HTTP/1.1
Host: your-domain.com
Content-Type: application/json
X-Webhook-Event: generated_avatar_video_success
X-Webhook-Signature: 7256c87be255861cbbe92f4a04a4500176b045a287f258e32e5b6c6b96d7f290
User-Agent: JoggAI-Webhook/2.0
```

### Signature Verification Examples

#### Go

```go theme={null}
func VerifyWebhookSignature(payload []byte, signature, secret string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(payload)
    expectedSignature := hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(signature), []byte(expectedSignature))
}
```

#### Python

```python theme={null}
import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)
```

#### Node.js

```javascript theme={null}
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
    const expected = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');
    return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expected)
    );
}
```

## Best Practices

<CardGroup>
  <Card title="Quick Response" icon="bolt">
    Return 200 status code within 5 seconds
  </Card>

  <Card title="Async Processing" icon="clock">
    Return immediately, process business logic in background
  </Card>

  <Card title="Idempotent Handling" icon="check-double">
    Same event may be sent multiple times, ensure idempotency
  </Card>

  <Card title="Error Retry" icon="rotate">
    System automatically retries failed webhooks
  </Card>
</CardGroup>


# Delete Webhook Endpoint
Source: https://docs.jogg.ai/api-reference/v2/Webhook/DeleteWebhookEndpoint

DELETE /v2/endpoint/{endpoint_id}
Remove a webhook endpoint from your account.
This action cannot be undone and the endpoint will stop receiving events immediately.


Remove a webhook endpoint from your account.

This action cannot be undone and the endpoint will stop receiving events immediately.

## Use Cases

* Remove webhooks that are no longer needed
* Clean up inactive endpoints
* Stop event notifications

## Important Notes

<Warning>
  Deleting a webhook endpoint cannot be reversed. All associated event subscriptions will be removed.
</Warning>

<Info>
  If you only need to temporarily stop receiving events, we recommend using [Update Webhook Endpoint](/api-reference/v2/Webhook/UpdateWebhookEndpoint) to set the status to `disabled` instead of deleting the endpoint.
</Info>


# List Webhook Endpoints
Source: https://docs.jogg.ai/api-reference/v2/Webhook/ListWebhookEndpoints

GET /v2/endpoints
Retrieve a list of all webhook endpoints configured for your account.
Webhooks allow you to receive real-time notifications about events in your JoggAI workspace.


Retrieve a list of all webhook endpoints configured in your account.

Webhooks allow you to receive real-time notifications about events in your JoggAI workspace.

<Info>
  **Limit**: Each user can create up to **20** webhook endpoints.
</Info>

## Use Cases

* View all configured webhook endpoints
* Manage event subscriptions
* Monitor webhook status
* Check enabled/disabled endpoints

## Response Fields

| Field         | Type    | Description                              |
| ------------- | ------- | ---------------------------------------- |
| `endpoint_id` | string  | Unique webhook endpoint identifier       |
| `url`         | string  | Webhook receiver URL                     |
| `secret`      | string  | Secret key for signature verification    |
| `status`      | string  | Endpoint status: `enabled` or `disabled` |
| `events`      | array   | List of subscribed event types           |
| `created_at`  | integer | Creation timestamp                       |

## Best Practices

<Tip>
  Regularly check webhook endpoint status to ensure critical event endpoints are `enabled`.
</Tip>

<Note>
  If you no longer need a webhook, we recommend using [Delete Webhook Endpoint](/api-reference/v2/Webhook/DeleteWebhookEndpoint) to remove it and free up your quota.
</Note>


# List Webhook Events
Source: https://docs.jogg.ai/api-reference/v2/Webhook/ListWebhookEvents

GET /v2/events
Get a list of all available webhook event types that you can subscribe to.
Each event type represents a specific action or status change in the system.


Get a list of all available webhook event types that you can subscribe to.

Each event type represents a specific action or status change in the system.

## Use Cases

* View all available event types
* Select events to subscribe to
* Understand event naming conventions

## Response Example

```json theme={null}
{
  "rid": "",
  "code": 0,
  "msg": "success",
  "data": {
    "events": [
      "generated_video_success",
      "generated_video_failed",
      "create_avatar_success",
      "create_avatar_failed",
      "generated_image_success",
      "generated_image_failed",
      "generated_motion_success",
      "generated_motion_failed",
      "generated_product_video_success",
      "generated_product_video_failed",
      "generated_avatar_video_success",
      "generated_avatar_video_failed",
      "generated_template_video_success",
      "generated_template_video_failed",
      "generated_translate_video_success",
      "generated_translate_video_failed",
      "generated_photo_avatar_success",
      "generated_photo_avatar_failed",
      "generated_product_avatar_success",
      "generated_product_avatar_failed",
      "generated_script_success",
      "generated_script_failed"
    ]
  }
}
```

## Available Event Types

### Video Generation Events

| Event Type                          | Description                         |
| ----------------------------------- | ----------------------------------- |
| `generated_video_success`           | Video generation succeeded          |
| `generated_video_failed`            | Video generation failed             |
| `generated_product_video_success`   | Product video generation succeeded  |
| `generated_product_video_failed`    | Product video generation failed     |
| `generated_avatar_video_success`    | Avatar video generation succeeded   |
| `generated_avatar_video_failed`     | Avatar video generation failed      |
| `generated_template_video_success`  | Template video generation succeeded |
| `generated_template_video_failed`   | Template video generation failed    |
| `generated_translate_video_success` | Video translation succeeded         |
| `generated_translate_video_failed`  | Video translation failed            |

### Avatar Generation Events

| Event Type                         | Description                       |
| ---------------------------------- | --------------------------------- |
| `create_avatar_success`            | Avatar creation succeeded         |
| `create_avatar_failed`             | Avatar creation failed            |
| `generated_photo_avatar_success`   | Photo avatar creation succeeded   |
| `generated_photo_avatar_failed`    | Photo avatar creation failed      |
| `generated_product_avatar_success` | Product avatar creation succeeded |
| `generated_product_avatar_failed`  | Product avatar creation failed    |

### AI Script Generation Events

| Event Type                 | Description                    |
| -------------------------- | ------------------------------ |
| `generated_script_success` | AI script generation succeeded |
| `generated_script_failed`  | AI script generation failed    |

### Image Generation Events

| Event Type                | Description                |
| ------------------------- | -------------------------- |
| `generated_image_success` | Image generation succeeded |
| `generated_image_failed`  | Image generation failed    |

### Motion Generation Events

| Event Type                 | Description                 |
| -------------------------- | --------------------------- |
| `generated_motion_success` | Motion generation succeeded |
| `generated_motion_failed`  | Motion generation failed    |

<Tip>
  We recommend subscribing to at least `*_success` and `*_failed` events to stay informed about task completion status.
</Tip>

## Webhook Payload Examples

When an event is triggered, your endpoint will receive a JSON payload similar to the following:

### Video Generation Success Event

```json theme={null}
{
  "event_id": "evt_123456789",
  "event": "generated_avatar_video_success",
  "timestamp": 1732806631,
  "data": {
    "video_id": "video_123456",
    "status": "completed",
    "video_url": "https://res.jogg.ai/video.mp4",
    "cover_url": "https://res.jogg.ai/cover.jpg",
    "duration": 30
  }
}
```

### Avatar Generation Success Event

```json theme={null}
{
  "event_id": "evt_987654321",
  "event": "generated_photo_avatar_success",
  "timestamp": 1732806631,
  "data": {
    "avatar_id": 12345,
    "status": "completed",
    "preview_url": "https://res.jogg.ai/avatar-preview.mp4"
  }
}
```

### Script Generation Success Event

```json theme={null}
{
  "event": "generated_script_success",
  "timestamp": 1732806631,
  "data": {
    "task_id": "task_123456",
    "status": "completed",
    "scripts": [
      {
        "script_style": "Storytime",
        "script_paragraphs": "Your generated script content..."
      }
    ]
  }
}
```

### Image Generation Success Event

```json theme={null}
{
  "event": "generated_image_success",
  "timestamp": 1732806631,
  "data": {
    "photo_id": "photo_123456",
    "photo_urls": [
      "https://res.jogg.ai/image1.jpg",
      "https://res.jogg.ai/image2.jpg"
    ]
  }
}
```

### Image Generation Failed Event

```json theme={null}
{
  "event": "generated_image_failed",
  "timestamp": 1732806631,
  "data": {
    "photo_id": "photo_123456",
    "error": "Image generation failed due to invalid parameters"
  }
}
```

### Motion Generation Success Event

```json theme={null}
{
  "event": "generated_motion_success",
  "timestamp": 1732806631,
  "data": {
    "motion_id": "motion_123456",
    "motion_url": "https://res.jogg.ai/motion.mp4",
    "photo_url": "https://res.jogg.ai/photo.jpg"
  }
}
```

### Motion Generation Failed Event

```json theme={null}
{
  "event": "generated_motion_failed",
  "timestamp": 1732806631,
  "data": {
    "motion_id": "motion_123456",
    "error": "Motion generation failed due to processing error"
  }
}
```

## Best Practices

<Info>
  * **Use idempotent processing**: The same event may be sent multiple times, ensure your logic handles this
  * **Implement retry logic**: The system will retry sending webhooks if processing fails
  * **Respond quickly**: Return a 2xx status code within 5 seconds to avoid timeouts
  * **Process asynchronously**: Return 200 immediately after receiving the event, then process business logic asynchronously
  * **Verify signatures**: Use the webhook secret to verify request authenticity
</Info>

## Event Naming Convention

Most events follow the `generated_{resource}_{status}` or `create_{resource}_{status}` naming pattern:

* `{resource}`: Resource type (e.g., `avatar_video`, `product_avatar`, `script`, `avatar`)
* `{status}`: Status (`success` or `failed`)

**Note:** Some legacy events use simpler naming (e.g., `generated_video_success`, `create_avatar_success`).


# Update Webhook Endpoint
Source: https://docs.jogg.ai/api-reference/v2/Webhook/UpdateWebhookEndpoint

PUT /v2/endpoint/{endpoint_id}
Update an existing webhook endpoint configuration including URL, status, and subscribed events.


Update an existing webhook endpoint configuration, including URL, status, and subscribed events.

## Use Cases

* Modify webhook receiver URL
* Update subscribed event types
* Enable or disable webhook
* Adjust event notification scope

## Status Management

<Tip>
  Set `status` to `disabled` to temporarily stop receiving events without deleting the endpoint configuration.
</Tip>

## Important Notes

<Warning>
  After updating the webhook endpoint, the new configuration takes effect immediately. Ensure the new URL is ready to receive requests.
</Warning>


# Welcome to JoggAI
Source: https://docs.jogg.ai/home/WelcometoJoggAI

At JoggAI, we enable creators, brands, and enterprises to generate high-quality, engaging AI-driven video content at scale — without the need for cameras, studios, or production teams. From lifelike AI avatar videos, AI video podcasts and AI video ads, every output is powered by cutting-edge generative AI video and voice technology. JoggAI empowers you to create faster, scale seamlessly, and deliver content that connects.

<div>
  <a href="/api-reference/v2/QuickStart/GettingStarted">
    Quick Start →
  </a>
</div>

## Key Features

<CardGroup>
  <Card title="Avatar Videos" icon="video" href="/api-reference/v2/API Documentation/CreateAvatarVideos">
    Create engaging videos with realistic AI avatars and lip-sync technology.
  </Card>

  <Card title="AI Ads Maker" icon="sparkles" href="/api-reference/v2/API Documentation/URLtoVideo">
    Turn product URLs into high-converting video ads in minutes.
  </Card>

  <Card title="Video Translation" icon="language" href="/api-reference/v2/API Documentation/VideoTranslation">
    Reach global audiences by translating video content seamlessly.
  </Card>

  <Card title="AI Script" icon="file-lines" href="/api-reference/v2/API Documentation/AIScripts">
    AI-powered script generation for your videos.
  </Card>
</CardGroup>

## See JoggAI in Action

<div>
  <Card>
    <div>
      <iframe title="YouTube video player" />
    </div>

    <div>
      <h3>
        A Quick Guide to Creating Realistic AI Avatars
      </h3>
    </div>
  </Card>

  <div>
    <Card>
      <div>
        <iframe title="YouTube video player" />
      </div>

      <div>
        <h4>
          Create AI Avatar Videos
        </h4>
      </div>
    </Card>

    <Card>
      <div>
        <iframe title="YouTube video player" />
      </div>

      <div>
        <h4>
          AI Video Ads in Minutes
        </h4>
      </div>
    </Card>

    <Card>
      <div>
        <iframe title="YouTube video player" />
      </div>

      <div>
        <h4>
          JoggAI API
        </h4>
      </div>
    </Card>
  </div>
</div>

## Need Help?

If you have any further questions about using the API, please don't hesitate to reach out to us at [support@jogg.ai](mailto:support@jogg.ai) and include your Discord username. Our dedicated support team is ready to assist you.