Catchups.ai Video creation API
  1. Video Generations
  • Account
    • Get authenticated account summary
      GET
  • Video Generations
    • List video generations
      GET
    • Create a video generation
      POST
    • Get video generation status
      GET
    • Get completed generation result
      GET
    • Cancel a video generation
      POST
  • Research
    • Create a researched video generation
      POST
  1. Video Generations

Create a video generation

POST
/v1/video-generations
Public customer entry point for prepared-source video generation requests. This endpoint does not crawl URLs or run research; send URL-only or topic-only inputs to /v1/research. Long-running work is accepted asynchronously and returned through the public generation status and result endpoints.

Request

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200OK
application/json
Existing generation returned for a matching idempotent retry.
Bodyapplication/json

🟢202Accepted
🟠400Bad Request
🟠401Unauthorized
🟠409
🟠422Parameter Error
🟠429
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location '/v1/video-generations' \
--header 'Idempotency-Key;' \
--header 'Content-Type: application/json' \
--data '{
    "projectId": "proj_01HXAMPLE",
    "source": {
        "mode": "topicBundle",
        "topic": "AI video workflow automation",
        "summary": "Teams are adopting automated source-to-video workflows for executive updates and social clips.",
        "keyPoints": [
            "Short-form video teams want repeatable generation from trusted source material.",
            "Brand-safe templates and automated captions reduce production review time."
        ],
        "sources": [
            {
                "id": "src_1",
                "url": "https://example.com/report",
                "title": "Example automation report",
                "publisher": "Example News",
                "publishedAt": "2026-05-10T09:00:00.000Z",
                "summary": "A concise source summary."
            }
        ],
        "images": [
            {
                "url": "https://example.com/topic-image.jpg",
                "caption": "Topic reference image"
            }
        ]
    },
    "video": {
        "durationTargetSeconds": 45,
        "aspectRatio": "9:16",
        "resolution": "1080p",
        "qualityTier": "balanced"
    },
    "language": {
        "content": "en",
        "output": "en"
    },
    "creative": {
        "format": "newsExplainer",
        "styleBrief": "fast newsroom explainer"
    },
    "postProduction": {
        "brand": "catchups",
        "enabled": true,
        "watermarkEnabled": true,
        "watermarkOpacity": 0.5
    },
    "metadata": {
        "externalId": "customer_generation_123"
    }
}'
Response Response Example
200 - Accepted generation
{
    "id": "job_01HXAMPLE",
    "status": "queued",
    "statusDetail": "Generation queued.",
    "url": "/v1/video-generations/job_01HXAMPLE",
    "resultUrl": "/v1/video-generations/job_01HXAMPLE/result",
    "idempotentReplay": false
}
Modified at 2026-05-24 15:07:59
Previous
List video generations
Next
Get video generation status
Built with