# Video AI video generation (scripts, generation, status) ## Generate video script > Generate a detailed video prompt and settings from a brief description. ```json {"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Video","description":"AI video generation (scripts, generation, status)"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/video/script":{"post":{"summary":"Generate video script","description":"Generate a detailed video prompt and settings from a brief description.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["brief"],"properties":{"brief":{"type":"string","description":"Brief description of the video"},"format":{"type":"string","enum":["product_showcase","lifestyle_aesthetic","ugc_style","before_after","cinematic_broll","logo_brand_reveal","tutorial_howto","testimonial_talking_head","seasonal_campaign","abstract_mood"]},"platform":{"type":"string"},"site_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Generated video script","content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string"},"suggested_duration":{"type":"number"},"suggested_aspect_ratio":{"type":"string"},"suggested_resolution":{"type":"string"},"shot_description":{"type":"string"},"negative_prompt":{"type":"string"}}}}}}},"tags":["Video"]}}}} ``` ## Create video generation job > Start a video generation job. Returns an ID to poll for status. ```json {"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Video","description":"AI video generation (scripts, generation, status)"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/video":{"post":{"summary":"Create video generation job","description":"Start a video generation job. Returns an ID to poll for status.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt","model","duration_seconds"],"properties":{"prompt":{"type":"string"},"model":{"type":"string","description":"Video model to use. Replicate-hosted models (require Replicate API key):\n`replicate:runway-gen-4.5`, `replicate:seedance-2.0`, `replicate:seedance-2.0-fast`,\n`replicate:kling-v3`, `replicate:veo-3.1-fast`, `replicate:grok-imagine-video`, `replicate:p-video`.\nWaveSpeed-hosted models (require WaveSpeed API key):\n`wavespeed:higgsfield-dop-i2v` (Higgsfield Director-of-Photography image-to-video, REQUIRES `start_image_url`, 5s clips at 720p).\n"},"duration_seconds":{"type":"number"},"aspect_ratio":{"type":"string","enum":["16:9","9:16","1:1","4:3","3:4","3:2","2:3"]},"resolution":{"type":"string","enum":["480p","720p","1080p"]},"negative_prompt":{"type":"string"},"start_image_url":{"type":"string","format":"uri","description":"Public URL of a still image to use as the first frame. REQUIRED for wavespeed:higgsfield-dop-i2v. Optional for Seedance, Grok, Kling, Veo, P-Video."},"end_image_url":{"type":"string","format":"uri","description":"Public URL of a still image to use as the final frame, creating a transition. Supported by Seedance (both), Kling v3, Veo 3.1, and Higgsfield DoP."},"motions":{"type":"array","description":"WaveSpeed/Higgsfield DoP only. 1-2 camera motions (REQUIRED by the model — defaults to a single \"Zoom Out\" if omitted). Available motions include \"Zoom Out\", \"360 Orbit\", \"3D Rotation\", \"Arc Left\", \"Arc Right\", \"Action Run\", \"Angel Wings\".","minItems":1,"maxItems":2,"items":{"type":"object","required":["motion","strength"],"properties":{"motion":{"type":"string"},"strength":{"type":"number","minimum":0,"maximum":1}}}},"wavespeed_variant":{"type":"string","enum":["dop-lite","dop-turbo","dop-preview"],"description":"WaveSpeed/Higgsfield DoP variant. dop-turbo (default) for balanced speed+quality, dop-lite for drafts, dop-preview for premium."},"site_id":{"type":"string","format":"uuid"},"use_brand_context":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Video generation job created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["progress"]}}}}}}},"tags":["Video"]}}}} ``` ## Get video status > Check the status of a video generation job. ```json {"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Video","description":"AI video generation (scripts, generation, status)"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/video/{id}":{"get":{"summary":"Get video status","description":"Check the status of a video generation job.","responses":{"200":{"description":"Video job status","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"status":{"type":"string"},"provider":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"video_type":{"type":"string","nullable":true},"meta":{"type":"object","nullable":true},"progress":{"type":"number","nullable":true},"duration_seconds":{"type":"number","nullable":true},"error_message":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}}}}}},"tags":["Video"]}}}} ``` ## DELETE /v1/video/{id} > Delete video ```json {"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Video","description":"AI video generation (scripts, generation, status)"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/video/{id}":{"delete":{"summary":"Delete video","responses":{"200":{"description":"Video deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}}}},"tags":["Video"]}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://learn.cuppa.ai/rest-api/video.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.