{ "openapi": "3.1.0", "info": { "title": "Video Effects API", "version": "1.0.0", "description": "Create a Kling preset-effects video task and receive a task id for later polling." }, "servers": [ { "url": "https://api.cometapi.com" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/kling/v1/videos/effects": { "post": { "summary": "Create a Kling video-effects task", "operationId": "video_effects", "description": "Submit an `effect_scene` plus a provider-specific `input` object. `callback_url` and `external_task_id` are optional.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "effect_scene", "input" ], "properties": { "effect_scene": { "type": "string", "description": "Kling preset effect scene. Single-image effects use `input.image`; two-person interaction effects use `input.images` with exactly two images." }, "input": { "type": "object", "description": "Effect-specific input payload. Single-image scenes require `image` and `duration`; two-person interaction scenes require exactly two `images` and `duration`.", "oneOf": [ { "title": "Single-image effect input", "required": [ "image", "duration" ], "not": { "required": [ "images" ] } }, { "title": "Two-person interaction effect input", "required": [ "images", "duration" ], "not": { "required": [ "image" ] } } ], "properties": { "model_name": { "type": "string", "description": "Model variant for two-person interaction effects. Omit to use the route default." }, "mode": { "type": "string", "description": "Generation mode for effects that support it. Use `std` or `pro`.", "enum": [ "std", "pro" ] }, "image": { "type": "string", "description": "Image URL or base64 image string for single-image effects. Use an image that meets Kling pixel requirements." }, "images": { "type": "array", "description": "Exactly two image URLs or base64 image strings for two-person interaction effects. Each image must meet Kling pixel requirements.", "minItems": 2, "maxItems": 2, "items": { "type": "string" } }, "duration": { "type": "string", "description": "Effect video length in seconds. Use `5` or `10` when the selected scene supports both." } } }, "callback_url": { "type": "string", "description": "Webhook URL for task status notifications. The server sends a callback when the task status changes." }, "external_task_id": { "type": "string", "description": "Optional user-defined task ID for your own tracking. Does not replace the system-generated task ID. Must be unique per account." } }, "default": { "effect_scene": "hug", "input": { "mode": "std", "images": [ "https://your-image-host/person-a.jpg", "https://your-image-host/person-b.jpg" ], "duration": "5" } } }, "examples": { "Default": { "summary": "Two-person interaction effect", "value": { "effect_scene": "hug", "input": { "mode": "std", "images": [ "https://your-image-host/person-a.jpg", "https://your-image-host/person-b.jpg" ], "duration": "5" } } } } } } }, "responses": { "200": { "description": "Task accepted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "data" ], "properties": { "code": { "type": "integer", "description": "Error code; specific error code definition\n" }, "message": { "type": "string", "description": "Error message\n" }, "data": { "type": "object", "required": [ "task_id", "task_status", "created_at", "updated_at" ], "properties": { "task_id": { "type": "string", "description": "Task ID, system generated\n" }, "task_status": { "type": "string", "description": "Task status, enumeration values: submitted, processing, succeed, failed\n" }, "task_info": { "type": "object", "additionalProperties": true }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } } } }, "example": { "code": 0, "message": "success", "data": { "task_id": "2032273960331935744", "task_status": "submitted", "task_info": {}, "created_at": 1773366844624, "updated_at": 1773366844624 } } } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "Default", "source": "curl https://api.cometapi.com/kling/v1/videos/effects \\\n -H \"Authorization: Bearer $COMETAPI_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"effect_scene\": \"hug\",\n \"input\": {\n \"mode\": \"std\",\n \"images\": [\n \"https://your-image-host/person-a.jpg\",\n \"https://your-image-host/person-b.jpg\"\n ],\n \"duration\": \"5\"\n }\n }'\n" }, { "lang": "Python", "label": "Default", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.cometapi.com/kling/v1/videos/effects\",\n headers={\"Authorization\": \"Bearer \" + os.environ[\"COMETAPI_KEY\"]},\n json={\n \"effect_scene\": \"hug\",\n \"input\": {\n \"mode\": \"std\",\n \"images\": [\n \"https://your-image-host/person-a.jpg\",\n \"https://your-image-host/person-b.jpg\"\n ],\n \"duration\": \"5\"\n }\n },\n)\n\nresult = response.json()\nprint(result.get(\"code\"), result.get(\"data\", {}).get(\"task_id\"))\n" }, { "lang": "JavaScript", "label": "Default", "source": "const response = await fetch(\"https://api.cometapi.com/kling/v1/videos/effects\", {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.COMETAPI_KEY}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"effect_scene\": \"hug\",\n \"input\": {\n \"mode\": \"std\",\n \"images\": [\n \"https://your-image-host/person-a.jpg\",\n \"https://your-image-host/person-b.jpg\"\n ],\n \"duration\": \"5\"\n }\n }),\n});\n\nconst result = await response.json();\nconsole.log(result.code, result.data?.task_id);\n" } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer token authentication. Use your CometAPI key." } } } }