Create a researched video generation

POST

/v1/research

Accepts a short topic or URL, runs the configured research provider, and creates a video generation from the researched source bundle. Callers may also pass a normal video-generation source payload or prepared research fields.

Request

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200OK

application/json

Existing research-backed generation replayed from an idempotency key.

Bodyapplication/json

🟢202Accepted

🟠400Bad Request

🟠401Unauthorized

🟠409

🟠422Parameter Error

🟠429

🔴503Service Unavailable

Request Example

Shell

JavaScript

Java

Swift

cURL

Live research from URLPrepared research

curl --location '/v1/research' \
--header 'Idempotency-Key;' \
--header 'Content-Type: application/json' \
--data '{
    "projectId": "proj_01HXAMPLE",
    "input": "https://example.com/article",
    "mode": "url",
    "video": {
        "durationTargetSeconds": 30,
        "aspectRatio": "9:16",
        "resolution": "1080p",
        "qualityTier": "balanced"
    },
    "creative": {
        "format": "topicCatchup"
    },
    "metadata": {
        "externalId": "customer_research_123"
    }
}'

Response Example

200 - Accepted researched generation

{
    "id": "job_01HRESEARCH",
    "status": "queued",
    "statusDetail": "Generation queued.",
    "url": "/v1/video-generations/job_01HRESEARCH",
    "resultUrl": "/v1/video-generations/job_01HRESEARCH/result",
    "idempotentReplay": false,
    "research": {
        "status": "live_research",
        "topic": "AI video workflow automation"
    }
}

Modified at 2026-05-24 15:07:59

Cancel a video generation