> ## 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.

# Auto Video API (workflow)

> Complete documentation for the auto video generation workflow + status polling

# Auto Video API (workflow)

This API generates a full video automatically from a listing (description + images). The server will:

* pick **up to 5** images (depending on how many you provide)
* generate a short marketing text per selected image
* generate video clips (one per selected image)
* render the final video

The workflow uses **two endpoints**:

* **1) POST** `"/api/video-editor/generate/video/auto"`: starts a generation and returns an `id`
* **2) GET** `"/api/video-editor/generate/video/auto/{id}"`: polls the status (and triggers next server-side steps)

## Authentication

All requests must include:

* `x-api-key: YOUR_API_KEY`

## 1) Start a generation

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

### 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="image_urls" type="array" required>
  Array of image URLs. **Minimum 1**.
</ParamField>

<ParamField body="description" type="string" required>
  Listing description (min 10 chars). Detected language is used for generated
  texts.
</ParamField>

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

<ParamField body="colors" type="array">
  Two colors `[background, text]` (e.g. `["#1a1a2e", "#ffffff"]`). Optional.
</ParamField>

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

<ParamField body="music" type="string">
  Music value (internal identifier / value expected by your setup). Optional.
</ParamField>

<ParamField body="displayLogo" type="boolean">
  Whether to display a logo. Default: `false`.
</ParamField>

<ParamField body="logoUrl" type="string">
  Logo URL (required if `displayLogo=true`). Optional.
</ParamField>

<ParamField body="webhookUrl" type="string">
  Called by IACrea when the video is **DONE** (see Webhook section). Optional.
</ParamField>

### Responses

#### 201 — Started

<ResponseField name="id" type="string">
  Auto generation id. Use it with `GET /api/video-editor/generate/video/auto/   {id}`.
</ResponseField>

<ResponseField name="status" type="string">
  Initial status, typically `"PENDING"`.
</ResponseField>

<ResponseField name="generatedContent" type="array">
  List of clips/sequences being generated (one per selected image). Each item
  contains `id`, `url`, `effect`, `format`, `category`, `text`, `status`.
</ResponseField>

<ResponseField name="analysis" type="object">
  AI analysis output (selections).
</ResponseField>

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

<ResponseField name="creditsUsed" type="number">
  Used credits.
</ResponseField>

#### 400 — Validation error

Returned when the request body is invalid (e.g. empty `image_urls`, invalid URL, description too short, etc.).

#### 401 — Unauthorized

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

#### 500 — Server error

Server-side failure.

### Example (curl)

```bash theme={null}
curl --request POST \
  --url 'https://iacrea.com/api/video-editor/generate/video/auto' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "image_urls": ["https://example.com/1.jpg"],
    "description": "Bright apartment with a terrace, near downtown.",
    "format": "landscape",
    "webhookUrl": "https://your-app.com/webhooks/iacrea/video-auto"
  }'
```

## 2) Poll a generation

<ParamField path="GET /api/video-editor/generate/video/auto/{id}" />

### Headers

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

### Main responses

This endpoint is **idempotent** and can be polled. It returns a JSON object with a `status` field and, depending on the status, additional fields.

#### 200 — `status: "GENERATING_VIDEO"`

Clips are being generated. Also returns credits and `generatedContent`.

#### 200 — `status: "START_RENDERING_VIDEO"`

All sequences are ready; final render starts.

* `progress: 0`

#### 200 — `status: "RENDERING_VIDEO"`

Final render in progress.

* `progress`: a number you can display as-is.

#### 200 — `status: "DONE"`

Final video is ready.

* `url`: video URL
* `generatedContent`
* `creditsTotal`, `creditsUsed`

#### 200 — `status: "PENDING"`

Transient state; may be returned if the server needs to re-generate errored sequences.

#### 4xx/5xx

* `401` if API key is missing/invalid
* `404` if `id` is not found
* `500` on server errors

### Example (curl)

```bash theme={null}
curl --request GET \
  --url 'https://iacrea.com/api/video-editor/generate/video/auto/ID_FROM_POST' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Webhook (optional)

If `webhookUrl` is provided in the `POST`, IACrea will call your endpoint when the final video is ready:

* Method: `POST`
* Header: `Content-Type: application/json`
* Body:

```json theme={null}
{
  "id": "GENERATION_ID",
  "status": "DONE",
  "url": "https://...mp4"
}
```

### Integration recommendations

* **Polling**: call `GET /api/video-editor/generate/video/auto/{id}` every 2–5 seconds until `DONE` (or `ERROR`).
* **Timeout**: implement a client timeout (e.g. 10–20 minutes) depending on render times.
* **Resilience**: if you get `"PENDING"` after `"GENERATING_VIDEO"`, keep polling; the server may retry failed sequences.