{ "openapi": "3.1.0", "info": { "title": "Create Video API", "version": "1.0.0", "description": "Create an asynchronous Sora video job through CometAPI. Poll GET /v1/videos/{video_id} for status and GET /v1/videos/{video_id}/content for the final file." }, "servers": [ { "url": "https://api.cometapi.com" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer token authentication. Use your CometAPI key." } } }, "paths": { "/v1/videos": { "post": { "summary": "Create a Sora video job", "operationId": "create_video", "description": "Start a Sora render job from a prompt and, optionally, one reference image. Save the returned video id and poll the retrieve endpoint until the job completes.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "Text prompt that describes the video you want to create.", "example": "A paper airplane glides across a desk." }, "model": { "type": "string", "description": "Sora model ID. Choose an available model from the [Models page](/overview/models).", "default": "sora-2", "example": "sora-2" }, "seconds": { "type": "string", "enum": [ "4", "8", "12", "16", "20" ], "description": "Clip duration in seconds. Use 4, 8, 12, 16, or 20.", "default": "4", "example": "4" }, "size": { "type": "string", "enum": [ "720x1280", "1280x720", "1024x1792", "1792x1024" ], "description": "Output resolution formatted as width x height. Use 1280x720 or 720x1280 for standard Sora output. Use 1792x1024 or 1024x1792 with a Pro model when you need larger Pro output.", "default": "1280x720", "example": "1280x720" }, "input_reference": { "type": "string", "format": "binary", "description": "Optional reference image uploaded as a file. The image should match the target size you request." } }, "default": { "prompt": "A paper airplane glides across a desk.", "model": "sora-2", "seconds": "4", "size": "1280x720" } }, "examples": { "Text to video": { "summary": "Text to video", "value": { "model": "sora-2", "prompt": "A paper boat drifts across a calm pond at sunrise", "seconds": "4", "size": "1280x720" } }, "With reference image": { "summary": "First-frame reference image. Replace input_reference with your image file.", "value": { "model": "sora-2", "prompt": "Animate gentle ripples across the water", "seconds": "4", "size": "1280x720", "input_reference": "@reference.png" } } } } } }, "responses": { "200": { "description": "Video job accepted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "created_at", "id", "model", "object", "progress", "seconds", "size", "status" ], "properties": { "created_at": { "type": "integer" }, "id": { "type": "string" }, "model": { "type": "string" }, "object": { "type": "string" }, "progress": { "type": "integer" }, "seconds": { "type": "string" }, "size": { "type": "string" }, "status": { "type": "string" } }, "example": { "created_at": 1773296991, "id": "video_69b25d5f467c81908733a56bc236b4df", "model": "sora-2", "object": "video", "progress": 0, "seconds": "4", "size": "1280x720", "status": "queued" } }, "example": { "id": "", "task_id": "", "object": "video", "model": "sora-2", "status": "queued", "progress": 0, "created_at": 1781079478, "seconds": "4", "size": "1280x720" } } } } }, "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=sora-2 \\\n -F prompt=\"A paper boat drifts across a calm pond at sunrise\" \\\n -F seconds=4 \\\n -F size=1280x720\n" }, { "lang": "Shell", "label": "With reference image", "source": "curl https://api.cometapi.com/v1/videos \\\n -H \"Authorization: Bearer $COMETAPI_KEY\" \\\n -F model=sora-2 \\\n -F prompt=\"Animate gentle ripples across the water\" \\\n -F seconds=4 \\\n -F size=1280x720 \\\n -F input_reference=@reference.png\n" }, { "lang": "Python", "label": "Text to video", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.cometapi.com/v1/videos\",\n headers={\"Authorization\": \"Bearer \" + os.environ[\"COMETAPI_KEY\"]},\n data={\n \"model\": \"sora-2\",\n \"prompt\": \"A paper boat drifts across a calm pond at sunrise\",\n \"seconds\": \"4\",\n \"size\": \"1280x720\",\n },\n)\n\nvideo = response.json()\nprint(video[\"id\"], video[\"status\"]) # poll GET /v1/videos/{id} until completed\n" }, { "lang": "Python", "label": "With reference image", "source": "import os\nimport requests\n\nwith open(\"reference.png\", \"rb\") as image:\n response = requests.post(\n \"https://api.cometapi.com/v1/videos\",\n headers={\"Authorization\": \"Bearer \" + os.environ[\"COMETAPI_KEY\"]},\n data={\n \"model\": \"sora-2\",\n \"prompt\": \"Animate gentle ripples across the water\",\n \"seconds\": \"4\",\n \"size\": \"1280x720\",\n },\n files={\"input_reference\": image},\n )\n\nvideo = response.json()\nprint(video[\"id\"], video[\"status\"])\n" }, { "lang": "JavaScript", "label": "Text to video", "source": "const form = new FormData();\nform.append(\"model\", \"sora-2\");\nform.append(\"prompt\", \"A paper boat drifts across a calm pond at sunrise\");\nform.append(\"seconds\", \"4\");\nform.append(\"size\", \"1280x720\");\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 video = await response.json();\nconsole.log(video.id, video.status); // poll GET /v1/videos/{id} until completed\n" }, { "lang": "JavaScript", "label": "With reference image", "source": "import { readFile } from \"node:fs/promises\";\n\nconst form = new FormData();\nform.append(\"model\", \"sora-2\");\nform.append(\"prompt\", \"Animate gentle ripples across the water\");\nform.append(\"seconds\", \"4\");\nform.append(\"size\", \"1280x720\");\nform.append(\"input_reference\", new Blob([await readFile(\"reference.png\")], { type: \"image/png\" }), \"reference.png\");\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 video = await response.json();\nconsole.log(video.id, video.status);\n" } ] } } } }