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

# Video Creation API

> Create a full video with intro, outro, animated sequences, transitions and before/after effects

# Video Creation API

Creates a full video with multiple sequences. Each sequence can contain media (images or videos) animated according to the specified animation type. You can add an intro, an outro, transitions between sequences, a logo, and before/after effects.

<ParamField path="POST /api/video-editor/generate/video" />

## Authentication

All requests must include the header:

* `x-api-key: YOUR_API_KEY`

## Headers

<ParamField header="x-api-key" type="string" required>
  Your IACrea API key
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

## Request Body

<ParamField body="video" type="object" required>
  Video object containing all sequences and parameters
</ParamField>

<ParamField body="video.format" type="string" required>
  Video format: `"landscape" | "portrait" | "square"`
</ParamField>

<ParamField body="video.template" type="string">
  Video template. Default: `"SaleProperty"`. Optional.
</ParamField>

<ParamField body="video.music" type="string">
  Background music URL. Optional.
</ParamField>

<ParamField body="video.font" type="string">
  Font (e.g. `"Inter"`). Default: `"Inter"`. Optional.
</ParamField>

<ParamField body="video.colors" type="array" required>
  Array of two colors `[background, text]` (e.g. `["#1a1a2e", "#ffffff"]`).
  First color is background, second is text color.
</ParamField>

<ParamField body="video.displayLogo" type="boolean" required>
  Enables logo display on video/image sequences (top right corner,
  100 px). Logo on intro/outro is controlled separately via
  `sequence.data.displayLogo`.
</ParamField>

<ParamField body="video.logoUrl" type="string">
  Logo URL. Required if `displayLogo=true` or if you want to show the
  logo on intros/outros. Optional.
</ParamField>

## Sequences

<ParamField body="video.sequences" type="array" required>
  Ordered array of video sequences. Each sequence represents a clip in
  the final video. Sequences are composed in the order of their
  `order` field.
</ParamField>

<ParamField body="video.sequences[].order" type="number" required>
  Display order of the sequence in the video (starts at 0). Intro must
  be first (`0`), outro last.
</ParamField>

<ParamField body="video.sequences[].duration" type="number" required>
  Sequence duration in seconds. - `"video"` sequences: max 5 seconds
  (capped automatically) - `"intro"` sequences: 2 to 5 seconds (recommended
  : 3) - `"outro"` sequences: 3 to 5 seconds (recommended: 5) - `"image"`
  sequences: unlimited
</ParamField>

<ParamField body="video.sequences[].type" type="string" required>
  Sequence type: - `"intro"` — Introduction screen (logo + intro text) -
  `"outro"` — End screen (logo + contact or text) - `"video"` — Animated
  video sequence (triggers AI generation) - `"image"` — Static image
  sequence - `"beforeAfter"` — Before/after sequence (static comparison
  slide)
</ParamField>

<ParamField body="video.sequences[].animationType" type="string" required>
  Animation type. Possible values:

  **Camera movements:**

  * `"CAMERA_PUSH_IN"` — Zoom in
  * `"CAMERA_PUSH_OUT"` — Zoom out
  * `"CAMERA_MOVE_RIGHT"` — Move right
  * `"CAMERA_CRANE_UP"` — Move up
  * `"CAMERA_ORBIT_LEFT"` — Rotate left

  **Automatic AI effects:**

  * `"AUTO_EFFECTS"` — Automatic animation (AI-generated prompt)
  * `"AUTO_REVERSE"` — Reversed automatic animation

  **Special effects:**

  * `"REALTOR_SMILING"` — Real estate agent portrait animation

  **Before/After (require 2 images):**

  * `"BEFORE_AFTER_INTERIOR"` — Interior transformation (progressive staging)
  * `"BEFORE_AFTER_EXTERIOR"` — Exterior transformation (landscaping)
  * `"BEFORE_AFTER_DECLUTTER"` — Declutter (furniture disappearing)
  * `"BEFORE_AFTER_RENOVATION"` — Renovation (timelapse with renovation team)

  **No animation:**

  * `"none"` — No animation
  * `"fade"` — Simple fade
</ParamField>

## Media

<ParamField body="video.sequences[].medias" type="array" required>
  Array of media for this sequence. At least one media required for
  `"video"` and `"image"` types. `"intro"` and `"outro"` sequences do not
  need media (empty array `[]`).
</ParamField>

<ParamField body="video.sequences[].medias[].url" type="string" required>
  Source image or video URL. For BEFORE\_AFTER effects, this is the
  **"before"** image.
</ParamField>

<ParamField body="video.sequences[].medias[].start" type="number" required>
  Media start time in the sequence (in seconds). Usually `0`.
</ParamField>

<ParamField body="video.sequences[].medias[].end" type="number" required>
  Media end time in the sequence (in seconds). Must match duration.
</ParamField>

<ParamField body="video.sequences[].medias[].order" type="number">
  Media order in the sequence. Optional. Default: `0`.
</ParamField>

<ParamField body="video.sequences[].medias[].selected" type="boolean">
  Active media in the sequence. Set `true` for the main media.
  Optional.
</ParamField>

## Sequence data

<ParamField body="video.sequences[].data" type="object">
  Additional data for the sequence. Content varies by sequence type.
</ParamField>

### Intro data (`type: "intro"`)

<ParamField body="video.sequences[].data.description" type="string">
  Text displayed under the logo (e.g. `"presents"`, `"For sale"`).
</ParamField>

<ParamField body="video.sequences[].data.displayLogo" type="boolean">
  Show logo (from `video.logoUrl`) on intro. Default: `true`.
</ParamField>

<ParamField body="video.sequences[].data.bg" type="string">
  Custom background color for intro (e.g. `"#1a1a2e"`). Default:
  first color from `video.colors`.
</ParamField>

### Outro data (`type: "outro"`)

<ParamField body="video.sequences[].data.avatar" type="string">
  Profile photo URL (agent, advisor). Displayed as a circle.
</ParamField>

<ParamField body="video.sequences[].data.displayAvatar" type="boolean">
  Show avatar on outro. Default: `true`.
</ParamField>

<ParamField body="video.sequences[].data.name" type="string">
  Name displayed on outro (e.g. `"John Doe"`).
</ParamField>

<ParamField body="video.sequences[].data.email" type="string">
  Email displayed on outro.
</ParamField>

<ParamField body="video.sequences[].data.tel" type="string">
  Phone displayed on outro.
</ParamField>

<ParamField body="video.sequences[].data.displayLogo" type="boolean">
  Show logo (from `video.logoUrl`) on outro. Default: `true`.
</ParamField>

<ParamField body="video.sequences[].data.bg" type="string">
  Custom background color for outro.
</ParamField>

For `Interview` and `Sample` (generic) templates:

<ParamField body="video.sequences[].data.title" type="string">
  Title displayed on outro.
</ParamField>

<ParamField body="video.sequences[].data.description" type="string">
  Description displayed under the title.
</ParamField>

### Before/After data

<ParamField body="video.sequences[].data.afterImage" type="string">
  **Required for BEFORE\_AFTER effects.** URL of the "after"
  transformation image. The "before" image is provided via `medias[0].url`.
</ParamField>

## Transitions

Transitions define how a sequence **enters** relative to the previous one.
The transition is defined in the `data.transition` field of the target sequence.

<ParamField body="video.sequences[].data.transition" type="object">
  Entry transition configuration for this sequence.
</ParamField>

<ParamField body="video.sequences[].data.transition.type" type="string">
  Transition type: - `"fade"` — Crossfade (default) - `"wipe"` —
  Horizontal wipe - `"slide"` — Slide - `"flip"` — Flip - `"clock-wipe"` —
  Clock wipe - `"iris"` — Circular opening - `"none"` — No transition
</ParamField>

<ParamField body="video.sequences[].data.transition.duration" type="number">
  Transition duration in **frames** (1 to 120). At 30 fps: - `15` ≈ 0.5
  second - `20` ≈ 0.67 second (default) - `30` ≈ 1 second - `60` ≈ 2 seconds
</ParamField>

## Logo — Detailed behavior

The logo is controlled at two levels:

1. **Video level** (`video.displayLogo` + `video.logoUrl`):
   * Enables logo display in **top right corner** (100 px) on `"video"` and `"image"` type sequences.

2. **Sequence level** (`sequence.data.displayLogo`):
   * On `"intro"` and `"outro"`: the logo from `video.logoUrl` is displayed **centered** (200 px for intro, 150 px for outro).
   * Controlled individually by `sequence.data.displayLogo` (default `true`).
   * To hide the logo on a specific intro/outro, pass `"displayLogo": false` in its `data`.

## Webhook

<ParamField body="webhookUrl" type="string">
  Webhook URL to receive a notification when the video is complete.
  Optional.
</ParamField>

## Responses

### 201 — Created successfully

<ResponseField name="id" type="string">
  Unique identifier of the generated video. Use with `GET
      /api/video-editor/generate/video/{id}` to track progress.
</ResponseField>

<ResponseField name="generatedContent" type="array">
  List of generated content (one item per `"video"` type sequence). Each
  item contains: - `id`: Generation id - `url`: Source image URL -
  `effect`: Animation type - `format`: Video format - `status`: Status
  (`"pending" | "success" | "error"`)
</ResponseField>

<ResponseField name="creditsTotal" type="number">
  Remaining credits
</ResponseField>

<ResponseField name="creditsUsed" type="number">
  Credits used for this generation
</ResponseField>

### 400 — Validation error

Returned if the request body is invalid (missing sequence, invalid format, etc.).

### 401 — Unauthorized

Returned if `x-api-key` is missing or invalid.

### 500 — Server Error

Internal server error.

***

## Examples

### Example 1 — Basic video with intro + outro + logo

```bash theme={null}
curl --request POST \
  --url 'https://iacrea.com/api/video-editor/generate/video' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "video": {
      "format": "landscape",
      "template": "SaleProperty",
      "music": "https://example.com/music.mp3",
      "font": "Inter",
      "colors": ["#1a1a2e", "#ffffff"],
      "displayLogo": true,
      "logoUrl": "https://example.com/logo.png",
      "sequences": [
        {
          "order": 0,
          "duration": 3,
          "type": "intro",
          "animationType": "fade",
          "medias": [],
          "data": {
            "description": "presents",
            "displayLogo": true
          }
        },
        {
          "order": 1,
          "duration": 5,
          "type": "video",
          "animationType": "CAMERA_PUSH_IN",
          "medias": [
            {
              "url": "https://example.com/living-room.jpg",
              "start": 0,
              "end": 5,
              "order": 0,
              "selected": true
            }
          ],
          "data": {
            "description": "Bright living room with garden view"
          }
        },
        {
          "order": 2,
          "duration": 5,
          "type": "video",
          "animationType": "CAMERA_PUSH_OUT",
          "medias": [
            {
              "url": "https://example.com/bedroom.jpg",
              "start": 0,
              "end": 5,
              "order": 0,
              "selected": true
            }
          ]
        },
        {
          "order": 3,
          "duration": 5,
          "type": "outro",
          "animationType": "fade",
          "medias": [],
          "data": {
            "avatar": "https://example.com/agent-photo.jpg",
            "displayAvatar": true,
            "name": "John Doe",
            "email": "john.doe@agency.com",
            "tel": "+1 234 567 8900",
            "displayLogo": true
          }
        }
      ]
    },
    "webhookUrl": "https://your-app.com/webhooks/iacrea/video"
  }'
```

### Example 2 — Video with transitions between sequences

```bash theme={null}
curl --request POST \
  --url 'https://iacrea.com/api/video-editor/generate/video' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "video": {
      "format": "portrait",
      "template": "SaleProperty",
      "font": "Inter",
      "colors": ["#ffffff", "#333333"],
      "displayLogo": true,
      "logoUrl": "https://example.com/logo.png",
      "sequences": [
        {
          "order": 0,
          "duration": 3,
          "type": "intro",
          "animationType": "fade",
          "medias": [],
          "data": {
            "description": "New listing for sale",
            "displayLogo": true
          }
        },
        {
          "order": 1,
          "duration": 5,
          "type": "video",
          "animationType": "CAMERA_PUSH_IN",
          "medias": [
            {
              "url": "https://example.com/facade.jpg",
              "start": 0,
              "end": 5,
              "order": 0,
              "selected": true
            }
          ],
          "data": {
            "description": "Exterior view",
            "transition": {
              "type": "wipe",
              "duration": 25
            }
          }
        },
        {
          "order": 2,
          "duration": 5,
          "type": "video",
          "animationType": "CAMERA_ORBIT_LEFT",
          "medias": [
            {
              "url": "https://example.com/living-room.jpg",
              "start": 0,
              "end": 5,
              "order": 0,
              "selected": true
            }
          ],
          "data": {
            "transition": {
              "type": "slide",
              "duration": 20
            }
          }
        },
        {
          "order": 3,
          "duration": 5,
          "type": "video",
          "animationType": "CAMERA_CRANE_UP",
          "medias": [
            {
              "url": "https://example.com/kitchen.jpg",
              "start": 0,
              "end": 5,
              "order": 0,
              "selected": true
            }
          ],
          "data": {
            "transition": {
              "type": "flip",
              "duration": 30
            }
          }
        },
        {
          "order": 4,
          "duration": 5,
          "type": "outro",
          "animationType": "fade",
          "medias": [],
          "data": {
            "name": "Jane Smith",
            "email": "jane@agency.com",
            "tel": "+1 987 654 3210",
            "transition": {
              "type": "fade",
              "duration": 20
            }
          }
        }
      ]
    }
  }'
```

### Example 3 — BEFORE\_AFTER effect with two images

```bash theme={null}
curl --request POST \
  --url 'https://iacrea.com/api/video-editor/generate/video' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "video": {
      "format": "landscape",
      "template": "BeforeAfter",
      "font": "Inter",
      "colors": ["#0a0a0a", "#ffffff"],
      "displayLogo": true,
      "logoUrl": "https://example.com/logo.png",
      "sequences": [
        {
          "order": 0,
          "duration": 3,
          "type": "intro",
          "animationType": "fade",
          "medias": [],
          "data": {
            "description": "Interior transformation",
            "displayLogo": true
          }
        },
        {
          "order": 1,
          "duration": 5,
          "type": "video",
          "animationType": "BEFORE_AFTER_INTERIOR",
          "medias": [
            {
              "url": "https://example.com/empty-living-room.jpg",
              "start": 0,
              "end": 5,
              "order": 0,
              "selected": true
            }
          ],
          "data": {
            "afterImage": "https://example.com/staged-living-room.jpg",
            "description": "Living room before and after staging"
          }
        },
        {
          "order": 2,
          "duration": 5,
          "type": "video",
          "animationType": "BEFORE_AFTER_EXTERIOR",
          "medias": [
            {
              "url": "https://example.com/garden-before.jpg",
              "start": 0,
              "end": 5,
              "order": 0,
              "selected": true
            }
          ],
          "data": {
            "afterImage": "https://example.com/garden-after.jpg",
            "description": "Garden before and after landscaping",
            "transition": {
              "type": "wipe",
              "duration": 30
            }
          }
        },
        {
          "order": 3,
          "duration": 5,
          "type": "video",
          "animationType": "BEFORE_AFTER_DECLUTTER",
          "medias": [
            {
              "url": "https://example.com/cluttered-bedroom.jpg",
              "start": 0,
              "end": 5,
              "order": 0,
              "selected": true
            }
          ],
          "data": {
            "afterImage": "https://example.com/decluttered-bedroom.jpg",
            "description": "Bedroom before and after declutter",
            "transition": {
              "type": "iris",
              "duration": 25
            }
          }
        },
        {
          "order": 4,
          "duration": 5,
          "type": "video",
          "animationType": "BEFORE_AFTER_RENOVATION",
          "medias": [
            {
              "url": "https://example.com/room-to-renovate.jpg",
              "start": 0,
              "end": 5,
              "order": 0,
              "selected": true
            }
          ],
          "data": {
            "afterImage": "https://example.com/renovated-room.jpg",
            "description": "Full renovation with team",
            "transition": {
              "type": "fade",
              "duration": 20
            }
          }
        },
        {
          "order": 5,
          "duration": 5,
          "type": "outro",
          "animationType": "fade",
          "medias": [],
          "data": {
            "avatar": "https://example.com/agent-photo.jpg",
            "name": "Jane Smith",
            "email": "jane@agency.com",
            "tel": "+1 111 222 3344",
            "displayLogo": true
          }
        }
      ]
    }
  }'
```

### Example 4 — Logo hidden on intro but visible on sequences

```bash theme={null}
curl --request POST \
  --url 'https://iacrea.com/api/video-editor/generate/video' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "video": {
      "format": "square",
      "template": "SaleProperty",
      "font": "Inter",
      "colors": ["#2d3436", "#dfe6e9"],
      "displayLogo": true,
      "logoUrl": "https://example.com/logo.png",
      "sequences": [
        {
          "order": 0,
          "duration": 3,
          "type": "intro",
          "animationType": "fade",
          "medias": [],
          "data": {
            "description": "Discover this property",
            "displayLogo": false,
            "bg": "#000000"
          }
        },
        {
          "order": 1,
          "duration": 5,
          "type": "video",
          "animationType": "AUTO_EFFECTS",
          "medias": [
            {
              "url": "https://example.com/pool.jpg",
              "start": 0,
              "end": 5,
              "order": 0,
              "selected": true
            }
          ]
        },
        {
          "order": 2,
          "duration": 5,
          "type": "outro",
          "animationType": "fade",
          "medias": [],
          "data": {
            "name": "John Doe",
            "email": "john@luxury-realestate.com",
            "tel": "+1 000 000 0000",
            "displayLogo": true,
            "bg": "#000000"
          }
        }
      ]
    }
  }'
```

## Sample Response

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "generatedContent": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "url": "https://example.com/living-room.jpg",
      "effect": "CAMERA_PUSH_IN",
      "format": "landscape",
      "status": "pending"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440002",
      "url": "https://example.com/bedroom.jpg",
      "effect": "CAMERA_PUSH_OUT",
      "format": "landscape",
      "status": "pending"
    }
  ],
  "creditsTotal": 48,
  "creditsUsed": 2
}
```

## Important Notes

* `"video"` sequences automatically trigger AI animation generation from the provided image. **Each video sequence consumes 1 credit.**
* Maximum duration for a `"video"` sequence is **5 seconds** (capped automatically).
* `"intro"` and `"outro"` sequences do not consume credits (no AI generation).
* Use the returned `id` with `GET /api/video-editor/generate/video/{id}` to track progress.
* If a webhook is provided, you will receive a notification when the final video is ready.

### Intro / Outro Summary

| Property             | Intro              | Outro (SaleProperty) | Outro (Interview/Sample) |
| -------------------- | ------------------ | -------------------- | ------------------------ |
| `data.description`   | Intro text         | —                    | Description              |
| `data.displayLogo`   | Show centered logo | Show centered logo   | Show centered logo       |
| `data.bg`            | Background color   | Background color     | Background color         |
| `data.avatar`        | —                  | Profile photo        | —                        |
| `data.displayAvatar` | —                  | Show avatar          | —                        |
| `data.name`          | —                  | Name                 | —                        |
| `data.email`         | —                  | Email                | —                        |
| `data.tel`           | —                  | Phone                | —                        |
| `data.title`         | —                  | —                    | Title                    |

### Transitions Summary

Transitions are optional. Without a defined transition, the switch between sequences
uses the template default transition (fade of \~20 frames). To customize,
add `data.transition` on each desired sequence.

| Type         | Description                  |
| ------------ | ---------------------------- |
| `fade`       | Classic crossfade            |
| `wipe`       | Horizontal wipe              |
| `slide`      | Lateral slide                |
| `flip`       | 3D flip                      |
| `clock-wipe` | Clock-style wipe             |
| `iris`       | Circular opening from center |
| `none`       | Hard cut (no transition)     |

### Before/After Summary

| animationType             | Description                   | "Before" image  | "After" image     |
| ------------------------- | ----------------------------- | --------------- | ----------------- |
| `BEFORE_AFTER_INTERIOR`   | Progressive staging           | `medias[0].url` | `data.afterImage` |
| `BEFORE_AFTER_EXTERIOR`   | Landscaping                   | `medias[0].url` | `data.afterImage` |
| `BEFORE_AFTER_DECLUTTER`  | Declutter (furniture removed) | `medias[0].url` | `data.afterImage` |
| `BEFORE_AFTER_RENOVATION` | Renovation (team timelapse)   | `medias[0].url` | `data.afterImage` |

### Logo Summary

| Context              | Parameter                                     | Size   | Position         |
| -------------------- | --------------------------------------------- | ------ | ---------------- |
| `video`/`image` seq. | `video.displayLogo` + `video.logoUrl`         | 100 px | Top right corner |
| `intro` sequence     | `sequence.data.displayLogo` + `video.logoUrl` | 200 px | Centered         |
| `outro` sequence     | `sequence.data.displayLogo` + `video.logoUrl` | 150 px | Centered         |