Skip to main content

​
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

​

​
Headers

​
string
required
Your IACrea API key
​
string
required
Must be application/json

​
Request body

​
array
required
Array of image URLs. Minimum 1.
​
string
required
Listing description (min 10 chars). Detected language is used for generated texts.
​
string
Video format: "landscape" | "portrait" | "square". Default: "landscape".
​
array
Two colors [background, text] (e.g. ["#1a1a2e", "#ffffff"]). Optional.
​
string
Font (e.g. "Inter"). Optional.
​
string
Music value (internal identifier / value expected by your setup). Optional.
Whether to display a logo. Default: false.
​
string
Logo URL (required if displayLogo=true). Optional.
​
string
Called by IACrea when the video is DONE (see Webhook section). Optional.

​
Responses

​
201 — Started

​
string
Auto generation id. Use it with GET /api/video-editor/generate/video/auto/ {id}.
​
string
Initial status, typically "PENDING".
​
array
List of clips/sequences being generated (one per selected image). Each item contains id, url, effect, format, category, text, status.
​
object
AI analysis output (selections).
​
number
Remaining credits.
​
number
Used credits.

​
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)

​
2) Poll a generation

​

​
Headers

​
string
required
Your IACrea API key

​
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)

​
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:

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