{ "openapi": "3.1.0", "info": { "title": "Vidu Video Create API", "version": "1.0.0", "description": "Create an asynchronous Vidu Q3 text-to-video or image-to-video task through CometAPI. Save the returned id, poll GET /v1/videos/{task_id}, and download the completed MP4 file." }, "servers": [ { "url": "https://api.cometapi.com" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/videos": { "post": { "summary": "Create a Vidu Q3 video task", "operationId": "vidu_create_video", "description": "Create a Vidu Q3 text-to-video or image-to-video task. Send fields as multipart/form-data and upload reference images through input_reference.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ViduCreateRequest" }, "encoding": { "input_reference": { "contentType": "image/*" } }, "examples": { "text_to_video": { "summary": "Text-to-video", "value": { "model": "viduq3-turbo", "prompt": "An astronaut walks through soft blue fog with a slow cinematic camera move.", "seconds": "1" } }, "image_to_video": { "summary": "Image-to-video with an uploaded reference image", "value": { "model": "viduq3-turbo", "prompt": "Animate the uploaded image.", "seconds": "5", "size": "1280x720", "input_reference": "@reference.png" } } } } } }, "responses": { "200": { "description": "Task created. Store the returned id and poll GET /v1/videos/{task_id}.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ViduVideoTask" }, "example": { "id": "task_example", "task_id": "task_example", "object": "video", "model": "viduq3-turbo", "status": "queued", "progress": 0, "created_at": 1779938152 } } } }, "400": { "description": "The request is missing a required field or contains a value that the selected model cannot use." }, "401": { "description": "The API key is missing or invalid." } }, "security": [ { "bearerAuth": [] } ], "x-codeSamples": [ { "lang": "Shell", "label": "Text-to-video", "source": "curl https://api.cometapi.com/v1/videos \\\n -H \"Authorization: Bearer $COMETAPI_KEY\" \\\n -F model=viduq3-turbo \\\n -F 'prompt=An astronaut walks through soft blue fog with a slow cinematic camera move.' \\\n -F seconds=1" }, { "lang": "Python", "label": "Text-to-video", "source": "import os\nimport requests\n\nfields = [\n (\"model\", (None, \"viduq3-turbo\")),\n (\"prompt\", (None, \"An astronaut walks through soft blue fog with a slow cinematic camera move.\")),\n (\"seconds\", (None, \"1\")),\n]\n\nresponse = requests.post(\n \"https://api.cometapi.com/v1/videos\",\n headers={\"Authorization\": \"Bearer \" + os.environ[\"COMETAPI_KEY\"]},\n files=fields,\n timeout=120,\n)\n\nresponse.raise_for_status()\nprint(response.json())\n" }, { "lang": "JavaScript", "label": "Text-to-video", "source": "const form = new FormData();\nform.append(\"model\", \"viduq3-turbo\");\nform.append(\"prompt\", \"An astronaut walks through soft blue fog with a slow cinematic camera move.\");\nform.append(\"seconds\", \"1\");\n\nconst response = await fetch(\"https://api.cometapi.com/v1/videos\", {\n method: \"POST\",\n headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` },\n body: form,\n});\n\nconst result = await response.json();\nconsole.log(result);\n" }, { "lang": "Shell", "label": "Image-to-video", "source": "curl https://api.cometapi.com/v1/videos \\\n -H \"Authorization: Bearer $COMETAPI_KEY\" \\\n -F 'model=viduq3-turbo' \\\n -F 'prompt=Animate the uploaded image.' \\\n -F 'seconds=5' \\\n -F 'size=1280x720' \\\n -F 'input_reference=@reference.png;type=image/png'" }, { "lang": "Python", "label": "Image-to-video", "source": "import os\n\nimport requests\n\nwith open(\"reference.png\", \"rb\") as reference:\n response = requests.post(\n \"https://api.cometapi.com/v1/videos\",\n headers={\n \"Authorization\": \"Bearer \"\n + os.environ[\"COMETAPI_KEY\"]\n },\n data={\n \"model\": \"viduq3-turbo\",\n \"prompt\": \"Animate the uploaded image.\",\n \"seconds\": \"5\",\n \"size\": \"1280x720\",\n },\n files={\n \"input_reference\": (\n \"reference.png\",\n reference,\n \"image/png\",\n )\n },\n timeout=120,\n )\n\nresponse.raise_for_status()\nprint(response.json())\n" }, { "lang": "JavaScript", "label": "Image-to-video", "source": "import { readFile } from \"node:fs/promises\";\n\nconst reference = await readFile(\"reference.png\");\nconst form = new FormData();\nform.append(\"model\", \"viduq3-turbo\");\nform.append(\"prompt\", \"Animate the uploaded image.\");\nform.append(\"seconds\", \"5\");\nform.append(\"size\", \"1280x720\");\nform.append(\n \"input_reference\",\n new Blob([reference], { type: \"image/png\" }),\n \"reference.png\",\n);\n\nconst response = await fetch(\"https://api.cometapi.com/v1/videos\", {\n method: \"POST\",\n headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` },\n body: form,\n});\n\nconst result = await response.json();\nconsole.log(result);\n" } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer authentication. Use your CometAPI API key." } }, "schemas": { "ViduCreateRequest": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "description": "Vidu Q3 model ID for this route. Choose an available model from the Models page.", "example": "viduq3-turbo" }, "prompt": { "type": "string", "description": "Text prompt that describes the video to generate. For image-to-video, describe the motion and camera behavior that should animate the reference image.", "example": "An astronaut walks through soft blue fog with a slow cinematic camera move." }, "seconds": { "type": "string", "description": "Requested clip duration in seconds. Use an integer from 1 through 16. Default is 5.", "example": "1" }, "size": { "type": "string", "description": "Supported WxH size values: 960x528, 1280x720, 1920x1080. Default is 1280x720." }, "input_reference": { "type": "string", "format": "binary", "description": "One reference image file for image-to-video. Omit this field for text-to-video. The file can be up to 20 MB. The image guides the composition and appearance of the generated video." } }, "additionalProperties": false }, "ViduVideoTask": { "type": "object", "required": [ "id", "object", "model", "status", "progress", "created_at" ], "properties": { "id": { "type": "string", "description": "Task ID. Use this value with retrieve and content endpoints.", "example": "task_example" }, "task_id": { "type": "string", "description": "Compatibility alias for id when present.", "example": "task_example" }, "object": { "type": "string", "description": "Object type. Video tasks return video.", "example": "video" }, "model": { "type": "string", "description": "Model ID used for the task.", "example": "viduq3-turbo" }, "status": { "type": "string", "description": "Task lifecycle status. Poll until the value is completed, failed, or error.", "enum": [ "queued", "in_progress", "completed", "failed", "error" ], "example": "queued" }, "progress": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Task progress as a coarse percentage.", "example": 0 }, "created_at": { "type": "integer", "description": "Task creation time as a Unix timestamp in seconds.", "example": 1779938152 }, "completed_at": { "type": "integer", "description": "Task completion time as a Unix timestamp in seconds. This field appears on completed tasks.", "example": 1779938219 }, "video_url": { "type": "string", "description": "Temporary video delivery URL. This field appears on completed tasks.", "example": "" }, "error": { "type": "object", "description": "Failure details. This field appears when the task fails.", "additionalProperties": true } }, "additionalProperties": true } } } }