> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hooked.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Hook + Demo

> Create engaging Hook + Demo videos with text overlays and background media

<Note>
  **Try it out!** Use the API playground on the right to test the Hook + Demo endpoint directly. The schema is pre-configured for `hook_demo` type.
</Note>

## Overview

Hook + Demo videos are perfect for creating attention-grabbing content with text hooks displayed over demo media (images or videos). This format is ideal for:

* Product demonstrations with compelling hooks
* Social media content with text overlays
* Marketing videos with call-to-action text
* Quick promotional clips

<Info>
  Hook + Demo videos are generated in real-time, making them one of the fastest video types to create.
</Info>

***

## Endpoint

```
POST /v1/project/create/hook-demo
```

<Info>
  The endpoint is the same for all video types. Set `type: "hook_demo"` to create a Hook + Demo video.
</Info>

***

## Required Fields

<ParamField body="avatarId" type="string" required>
  Avatar template ID from `/v1/avatar/list`. This is the avatar that will appear in your Hook + Demo video.
</ParamField>

<ParamField body="text" type="string" required>
  The hook text to display on the video (1-5,000 characters). This is the main text that will appear as an overlay on your media.
</ParamField>

***

## Optional Fields

<ParamField body="name" type="string">
  Video name (max 100 characters)
</ParamField>

<ParamField body="media" type="array">
  Background media IDs (max 50). Array of media ID strings. These are the images or videos that will play behind your text hook.
</ParamField>

<ParamField body="musicId" type="string">
  Music template ID from `/v1/music/list` or custom music ID.
</ParamField>

<ParamField body="textSettings" type="object">
  Text display settings for the hook overlay

  <Expandable title="Text Settings Object">
    <ParamField body="preset" type="string" default="tiktok">
      Text preset style. Available presets include: `modern`, `tiktok`, `social`, `impact`, `slicedText`, `minimalMonochrome`, `highlight`, `gradient`, `neonFuture`, `avantGarde`, `glassmorphic`, `stageEffect`, `neonEffect`, `glowEffect`, `wrapEffect`
    </ParamField>

    <ParamField body="alignment" type="string" default="bottom">
      Text position on the video: `top`, `middle`, or `bottom`
    </ParamField>

    <ParamField body="textColor" type="string">
      Custom text color in hex format (e.g., `#ffffff`). Max 100 characters.
    </ParamField>

    <ParamField body="backgroundColor" type="string">
      Custom background color for the text box in hex format (e.g., `#000000`). Max 100 characters.
    </ParamField>

    <ParamField body="disabled" type="boolean" default="false">
      Set to `true` to hide the text overlay (useful when you only want the media)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="aspectRatio" type="string" default="ratio_9_16">
  Video aspect ratio:

  * `ratio_9_16`: Vertical (TikTok, Reels, Shorts) - **Recommended**
  * `ratio_16_9`: Horizontal (YouTube)
  * `ratio_1_1`: Square (Instagram)
</ParamField>

<ParamField body="webhook" type="string">
  HTTPS URL to receive completion notification (max 500 characters). **Highly recommended** for production use.
</ParamField>

<ParamField body="metadata" type="object">
  Custom metadata object (max 5KB). Store any additional data you need to associate with this video.

  ```json theme={null}
  {
    "campaignId": "summer2024",
    "productSku": "SKU-12345",
    "customField": "any value"
  }
  ```
</ParamField>

***

## Request Examples

### Basic Hook + Demo

```json theme={null}
{
  "avatarId": "6",
  "name": "Product Launch Hook",
  "text": "This changed everything..."
}
```

### With Background Media

```json theme={null}
{
  "avatarId": 6,
  "name": "Product Demo Video",
  "musicId": "music_id",
  "text": "Wait for it... This product will blow your mind!",
  "textSettings": {
    "preset": "impact",
    "alignment": "bottom",
    "disabled": false
  },
  "media": ["media_001", "media_002"],
  "aspectRatio": "ratio_9_16",
  "webhook": "https://yoursite.com/webhooks/video-complete"
}
```

### With Custom Colors and Metadata

```json theme={null}
{
  "avatarId": "6",
  "name": "Brand Campaign Hook",
  "text": "3 secrets they don't want you to know...",
  "textSettings": {
    "preset": "gradient",
    "alignment": "top",
    "textColor": "#00ff88",
    "backgroundColor": "transparent",
    "disabled": false
  },
  "media": ["media_bg"],
  "aspectRatio": "ratio_9_16",
  "webhook": "https://api.yoursite.com/hooks/hooked",
  "metadata": {
    "campaignId": "Q1-2024-hooks",
    "abTestVariant": "A",
    "internalRef": "MKT-1234"
  }
}
```

***

## Response

<ResponseExample>
  ```json Success Response theme={null}
  {
    "success": true,
    "data": {
      "videoId": "vid_ugc_abc123xyz",
      "projectId": "proj_hook_abc123xyz",
      "status": "COMPLETED"
    },
    "message": "Hook Demo successfully created"
  }
  ```

  ```json Error Response - Validation Error theme={null}
  {
    "success": false,
    "message": "text: Text is required"
  }
  ```

  ```json Error Response - Invalid Webhook theme={null}
  {
    "success": false,
    "message": "webhook: Must be a valid HTTPS URL"
  }
  ```
</ResponseExample>

***

## Webhook Notification

When your video is ready, we'll POST to your webhook URL:

```json Webhook Payload theme={null}
{
  "status": "COMPLETED",
  "data": {
    "videoId": "video_xyz789",
    "status": "COMPLETED",
    "url": "https://cdn.hooked.so/videos/xyz789.mp4",
    "shareUrl": "https://cdn.hooked.so/shared/xyz789.mp4",
    "metadata": {
      "projectId": "proj_hook_abc123xyz",
      "campaignId": "Q1-2024-hooks",
      "abTestVariant": "A"
    },
  },
  "message": "Video completed",
}
```

<Note>
  Your webhook endpoint must return a `200` status code. We'll retry up to 3 times if the request fails.
</Note>

***

## Text Presets

Available text presets for the `textSettings.preset` field:

| Preset              | Description                                                       |
| ------------------- | ----------------------------------------------------------------- |
| `modern`            | Clean, contemporary style with subtle shadows (Default)           |
| `tiktok`            | Viral & trendy style with bold outlines, perfect for social media |
| `social`            | White background with black text, great for readability           |
| `impact`            | Bold & commanding style with uppercase text and strong shadows    |
| `slicedText`        | Edgy & modern with colorful shadow effects (Pro)                  |
| `minimalMonochrome` | Ultra minimal style with lowercase text and subtle borders        |
| `highlight`         | Modern & distinctive with colored background boxes                |
| `gradient`          | Dynamic & modern with gradient text colors (Pro)                  |
| `neonFuture`        | Electric & bold with cyan neon glow effect                        |
| `avantGarde`        | Fashion forward with split gradient text (Pro)                    |
| `glassmorphic`      | Modern transparency effect with glass-like styling                |
| `stageEffect`       | Gradient stage effect with colorful text                          |
| `neonEffect`        | Electric glow with magenta neon shadows                           |
| `glowEffect`        | Soft white glow effect for elegant styling                        |
| `wrapEffect`        | Wrapped style with gradient text and blur backdrop                |

<Tip>
  You can override the preset colors using `textColor` and `backgroundColor` while keeping the preset's font styling and animations.
</Tip>

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Keep Hooks Short" icon="text">
    Effective hooks are 5-15 words. Get attention quickly.
  </Card>

  <Card title="Use High-Quality Media" icon="image">
    Upload media at least 1080p for best results. MP4 for videos, JPG/PNG for images.
  </Card>

  <Card title="Match Aspect Ratio" icon="crop">
    Ensure your media matches your target aspect ratio to avoid cropping.
  </Card>

  <Card title="Use Webhooks" icon="webhook">
    Always use webhooks in production instead of polling for video status.
  </Card>
</CardGroup>

***

## Common Use Cases

<AccordionGroup>
  <Accordion title="Social Media Hooks" icon="hashtag">
    Create attention-grabbing hooks for TikTok, Instagram Reels, or YouTube Shorts.

    ```json theme={null}
    {
      "avatarId": "6",
      "name": "Viral Hook",
      "text": "POV: You just discovered this hack",
      "textSettings": {
        "preset": "tiktok",
        "alignment": "middle",
        "textColor": "#00ff88",
        "backgroundColor": "transparent",
        "disabled": false
      },
      "aspectRatio": "ratio_9_16"
    }
    ```
  </Accordion>

  <Accordion title="Product Demos" icon="box">
    Showcase products with compelling text overlays.

    ```json theme={null}
    {
      "avatarId": "6",
      "name": "Product Feature",
      "text": "Watch what happens when you press this button...",
      "textSettings": {
        "preset": "modern",
        "alignment": "bottom",
        "textColor": "#00ff88",
        "backgroundColor": "transparent",
        "disabled": false
      },
      "media": ["demo_vid"]
    }
    ```
  </Accordion>

  <Accordion title="Testimonial Hooks" icon="quote-left">
    Highlight customer quotes or testimonials.

    ```json theme={null}
    {
      "avatarId": "6",
      "name": "Customer Quote",
      "text": "\"This saved me 10 hours every week\" - Sarah M.",
      "textSettings": {
        "preset": "highlight",
        "alignment": "middle",
        "textColor": "#ffffff",
        "backgroundColor": "#1a1a1a"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Error Handling

| Error                                             | Description          | Solution                                    |
| ------------------------------------------------- | -------------------- | ------------------------------------------- |
| `text: Text is required`                          | Missing hook text    | Add the `text` field with your hook content |
| `webhook: Must be a valid HTTPS URL`              | Invalid webhook URL  | Ensure webhook URL starts with `https://`   |
| `media: Cannot have more than 50 media items`     | Too many media items | Reduce media array to 50 items or fewer     |
| `textSettings.alignment: Invalid alignment value` | Invalid alignment    | Use `top`, `middle`, or `bottom`            |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="List Videos" icon="list" href="/api-reference/video/list">
    View all your created videos
  </Card>

  <Card title="Get Video Details" icon="info" href="/api-reference/video/details">
    Check video status and download URL
  </Card>

  <Card title="Webhooks Guide" icon="webhook" href="/guides/webhooks">
    Learn how to handle webhook notifications
  </Card>

  <Card title="Best Practices" icon="lightbulb" href="/guides/best-practices">
    Tips for creating effective videos
  </Card>
</CardGroup>


## OpenAPI

````yaml POST /v1/project/create/hook-demo
openapi: 3.0.0
info:
  title: Hooked API
  version: 1.0.0
  description: AI Video Generation API
servers:
  - url: https://api.hooked.so
security:
  - ApiKeyAuth: []
paths:
  /v1/project/create/hook-demo:
    post:
      tags:
        - Videos
      summary: Create Hook + Demo Video
      description: >-
        Create engaging Hook + Demo videos with text overlays and background
        media
      operationId: createHookDemo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
                - avatarId
                - text
              properties:
                avatarId:
                  type: string
                  description: Avatar template ID from /v1/avatar/list
                name:
                  type: string
                  description: Video name (max 100 characters)
                  maxLength: 100
                text:
                  type: string
                  description: The hook text to display on the video (1-5,000 characters)
                  minLength: 1
                  maxLength: 5000
                textSettings:
                  type: object
                  description: Text settings object
                  properties:
                    preset:
                      type: string
                      enum:
                        - modern
                        - tiktok
                        - social
                        - impact
                        - slicedText
                        - minimalMonochrome
                        - highlight
                        - gradient
                        - neonFuture
                        - avantGarde
                        - glassmorphic
                        - stageEffect
                        - neonEffect
                        - glowEffect
                        - wrapEffect
                      description: >-
                        Text preset style. Available presets: modern (Default),
                        tiktok, social, impact, slicedText, minimalMonochrome,
                        highlight, gradient, neonFuture, avantGarde,
                        glassmorphic, stageEffect, neonEffect, glowEffect,
                        wrapEffect
                      default: tiktok
                    alignment:
                      type: string
                      enum:
                        - top
                        - middle
                        - bottom
                      description: Text position on video
                      default: bottom
                    textColor:
                      type: string
                      description: 'Custom text color in hex format (e.g., #ffffff)'
                    backgroundColor:
                      type: string
                      description: Custom background color in hex format
                    disabled:
                      type: boolean
                      description: Set to true to hide the text overlay
                      default: false
                media:
                  type: array
                  description: Background media items (max 50)
                  maxItems: 50
                  items:
                    type: string
                    description: Unique media ID
                aspectRatio:
                  type: string
                  enum:
                    - ratio_9_16
                    - ratio_16_9
                    - ratio_1_1
                  description: Video aspect ratio
                  default: ratio_9_16
                musicId:
                  type: string
                  description: Music template ID from `/v1/music/list` or custom music ID.
                webhook:
                  type: string
                  description: HTTPS URL to receive completion notification
                  maxLength: 500
                metadata:
                  type: object
                  description: Custom metadata object (max 5KB)
            example:
              avatarId: '6'
              name: Product Launch Hook
              text: Wait for it... This changed EVERYTHING
              textSettings:
                preset: modern
                alignment: middle
                textColor: '#FFFFFF'
                backgroundColor: transparent
                disabled: false
              media: []
              aspectRatio: ratio_9_16
              webhook: https://yoursite.com/webhook
              musicId: your-custom-music-id
              metadata:
                campaignId: campaign_id
                variant: A
                createdBy: created_by
      responses:
        '200':
          description: Hook Demo created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  projectId:
                    type: string
                  data:
                    type: object
                    properties:
                      videoId:
                        type: string
                      projectId:
                        type: string
                      status:
                        type: string
                  message:
                    type: string
              example:
                success: true
                data:
                  projectId: proj_hook_abc123xyz
                  status: COMPLETED
                  webhook: https://yoursite.com/webhook
                message: Hook Demo successfully created
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
              example:
                success: false
                message: 'text: Text is required'
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````