{ "openapi": "3.1.0", "info": { "title": "Grok Video Generation API", "version": "1.0.0", "description": "Create an asynchronous Grok Imagine Video 1.5 job from text, a source image, or reference inputs." }, "servers": [ { "url": "https://api.cometapi.com" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Use your CometAPI API key as the bearer value." } } }, "paths": { "/grok/v1/videos/generations": { "post": { "summary": "Create a Grok video generation job", "operationId": "video_generation", "description": "Start a Grok Imagine Video 1.5 job. Save the returned `request_id`, then poll the result endpoint until the top-level status reaches a terminal state.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "model", "prompt" ], "allOf": [ { "not": { "required": [ "image", "reference_images" ] } }, { "not": { "required": [ "image", "reference_audios" ] } }, { "if": { "anyOf": [ { "required": [ "reference_images" ] }, { "required": [ "reference_audios" ] } ] }, "then": { "properties": { "resolution": { "description": "Reference-to-video resolution constraint.", "enum": [ "480p", "720p" ] } } } } ], "properties": { "model": { "type": "string", "enum": [ "grok-imagine-video-1.5" ], "description": "The Grok video model ID. Send this field explicitly so the request uses Grok Imagine Video 1.5.", "example": "grok-imagine-video-1.5" }, "prompt": { "type": "string", "minLength": 1, "description": "A description of the scene, motion, and audio. Reference-to-video prompts can identify inputs with tags such as `` and ``.", "example": "A paper boat glides across a quiet pond at sunrise." }, "duration": { "type": "integer", "minimum": 1, "maximum": 15, "default": 8, "description": "The output duration in seconds. Use an integer from 1 through 15." }, "aspect_ratio": { "type": "string", "description": "The output aspect ratio. Text-to-video uses `16:9` when omitted. Image-to-video uses the source image's aspect ratio when omitted.", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3" ], "example": "16:9" }, "resolution": { "type": "string", "description": "The output resolution. Reference-to-video requests support `480p` and `720p`; text-to-video and image-to-video also support `1080p`.", "enum": [ "480p", "720p", "1080p" ], "default": "480p" }, "image": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string", "description": "A public image URL or an image data URI such as `data:image/png;base64,`." } }, "description": "The source image for image-to-video. Do not combine this field with `reference_images` or `reference_audios`." }, "reference_images": { "type": "array", "minItems": 1, "maxItems": 7, "description": "Visual references for reference-to-video. Each item accepts a public image URL or image data URI. Do not combine this field with `image`.", "items": { "type": "object", "additionalProperties": false, "required": [ "url" ], "description": "One visual reference.", "properties": { "url": { "type": "string", "description": "A public image URL or an image data URI." } } } }, "reference_audios": { "type": "array", "minItems": 1, "maxItems": 3, "description": "Preset voice references for reference-to-video. Do not combine this field with `image`.", "items": { "type": "object", "additionalProperties": false, "required": [ "voice_id" ], "description": "One preset voice reference.", "properties": { "voice_id": { "type": "string", "minLength": 1, "description": "The preset voice ID, such as `eve`." } } } } } }, "examples": { "text-to-video": { "summary": "Text to video", "value": { "model": "grok-imagine-video-1.5", "prompt": "A paper boat glides across a quiet pond at sunrise.", "duration": 1, "aspect_ratio": "16:9", "resolution": "480p" } }, "image-url": { "summary": "Image URL", "value": { "model": "grok-imagine-video-1.5", "prompt": "Animate the clouds with a slow camera move and natural motion.", "image": { "url": "https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png" }, "duration": 1, "aspect_ratio": "16:9", "resolution": "720p" } }, "image-data-uri": { "summary": "Image data URI", "value": { "model": "grok-imagine-video-1.5", "prompt": "Animate the clouds drifting across the sky.", "image": { "url": "data:image/png;base64," }, "duration": 1, "aspect_ratio": "16:9", "resolution": "480p" } }, "reference-image": { "summary": "Reference image", "value": { "model": "grok-imagine-video-1.5", "prompt": "Use as the visual reference for a gentle cinematic pan.", "reference_images": [ { "url": "https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png" } ], "duration": 1, "aspect_ratio": "16:9", "resolution": "720p" } }, "reference-image-and-audio": { "summary": "Reference image and preset voice", "value": { "model": "grok-imagine-video-1.5", "prompt": "Use as the visual reference while says Welcome to the observatory.", "reference_images": [ { "url": "https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png" } ], "reference_audios": [ { "voice_id": "eve" } ], "duration": 1, "aspect_ratio": "16:9", "resolution": "720p" } } } } } }, "responses": { "200": { "description": "Request accepted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "request_id" ], "properties": { "request_id": { "type": "string", "description": "The deferred request ID used to poll `GET /grok/v1/videos/{request_id}`." } }, "example": { "request_id": "" } }, "example": { "request_id": "" } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "Text to video", "source": "curl https://api.cometapi.com/grok/v1/videos/generations \\\n -H \"Authorization: Bearer $COMETAPI_KEY\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary '{\n \"model\": \"grok-imagine-video-1.5\",\n \"prompt\": \"A paper boat glides across a quiet pond at sunrise.\",\n \"duration\": 1,\n \"aspect_ratio\": \"16:9\",\n \"resolution\": \"480p\"\n}'" }, { "lang": "Python", "label": "Text to video", "source": "import os\nimport requests\n\npayload = {\n \"model\": \"grok-imagine-video-1.5\",\n \"prompt\": \"A paper boat glides across a quiet pond at sunrise.\",\n \"duration\": 1,\n \"aspect_ratio\": \"16:9\",\n \"resolution\": \"480p\"\n}\n\nresponse = requests.post(\n \"https://api.cometapi.com/grok/v1/videos/generations\",\n headers={\n \"Authorization\": \"Bearer \" + os.environ[\"COMETAPI_KEY\"],\n \"Content-Type\": \"application/json\",\n },\n json=payload,\n timeout=180,\n)\nresponse.raise_for_status()\nprint(response.json()[\"request_id\"])" }, { "lang": "JavaScript", "label": "Text to video", "source": "const payload = {\n \"model\": \"grok-imagine-video-1.5\",\n \"prompt\": \"A paper boat glides across a quiet pond at sunrise.\",\n \"duration\": 1,\n \"aspect_ratio\": \"16:9\",\n \"resolution\": \"480p\"\n};\n\nconst response = await fetch(\n \"https://api.cometapi.com/grok/v1/videos/generations\",\n {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.COMETAPI_KEY}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify(payload),\n },\n);\nif (!response.ok) throw new Error(`Request failed: ${response.status}`);\nconsole.log((await response.json()).request_id);" }, { "lang": "Shell", "label": "Image URL", "source": "curl https://api.cometapi.com/grok/v1/videos/generations \\\n -H \"Authorization: Bearer $COMETAPI_KEY\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary '{\n \"model\": \"grok-imagine-video-1.5\",\n \"prompt\": \"Animate the clouds with a slow camera move and natural motion.\",\n \"image\": {\n \"url\": \"https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png\"\n },\n \"duration\": 1,\n \"aspect_ratio\": \"16:9\",\n \"resolution\": \"720p\"\n}'" }, { "lang": "Python", "label": "Image URL", "source": "import os\nimport requests\n\npayload = {\n \"model\": \"grok-imagine-video-1.5\",\n \"prompt\": \"Animate the clouds with a slow camera move and natural motion.\",\n \"image\": {\n \"url\": \"https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png\"\n },\n \"duration\": 1,\n \"aspect_ratio\": \"16:9\",\n \"resolution\": \"720p\"\n}\n\nresponse = requests.post(\n \"https://api.cometapi.com/grok/v1/videos/generations\",\n headers={\n \"Authorization\": \"Bearer \" + os.environ[\"COMETAPI_KEY\"],\n \"Content-Type\": \"application/json\",\n },\n json=payload,\n timeout=180,\n)\nresponse.raise_for_status()\nprint(response.json()[\"request_id\"])" }, { "lang": "JavaScript", "label": "Image URL", "source": "const payload = {\n \"model\": \"grok-imagine-video-1.5\",\n \"prompt\": \"Animate the clouds with a slow camera move and natural motion.\",\n \"image\": {\n \"url\": \"https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png\"\n },\n \"duration\": 1,\n \"aspect_ratio\": \"16:9\",\n \"resolution\": \"720p\"\n};\n\nconst response = await fetch(\n \"https://api.cometapi.com/grok/v1/videos/generations\",\n {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.COMETAPI_KEY}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify(payload),\n },\n);\nif (!response.ok) throw new Error(`Request failed: ${response.status}`);\nconsole.log((await response.json()).request_id);" }, { "lang": "Shell", "label": "Image data URI", "source": "{\n printf '%s' '{\"model\":\"grok-imagine-video-1.5\",\"prompt\":\"Animate the clouds drifting across the sky.\",\"image\":{\"url\":\"data:image/png;base64,'\n base64 < source.png | tr -d '\\n'\n printf '%s' '\"},\"duration\":1,\"aspect_ratio\":\"16:9\",\"resolution\":\"480p\"}'\n} | curl https://api.cometapi.com/grok/v1/videos/generations \\\n -H \"Authorization: Bearer $COMETAPI_KEY\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @-" }, { "lang": "Python", "label": "Image data URI", "source": "import base64\nimport os\nimport requests\n\nwith open(\"source.png\", \"rb\") as image_file:\n image_b64 = base64.b64encode(image_file.read()).decode()\n\npayload = {\n \"model\": \"grok-imagine-video-1.5\",\n \"prompt\": \"Animate the clouds drifting across the sky.\",\n \"image\": {\n \"url\": \"data:image/png;base64,\" + image_b64\n },\n \"duration\": 1,\n \"aspect_ratio\": \"16:9\",\n \"resolution\": \"480p\"\n}\n\nresponse = requests.post(\n \"https://api.cometapi.com/grok/v1/videos/generations\",\n headers={\n \"Authorization\": \"Bearer \" + os.environ[\"COMETAPI_KEY\"],\n \"Content-Type\": \"application/json\",\n },\n json=payload,\n timeout=180,\n)\nresponse.raise_for_status()\nprint(response.json()[\"request_id\"])" }, { "lang": "JavaScript", "label": "Image data URI", "source": "import { readFile } from \"node:fs/promises\";\n\nconst imageB64 = (await readFile(\"source.png\")).toString(\"base64\");\n\nconst payload = {\n \"model\": \"grok-imagine-video-1.5\",\n \"prompt\": \"Animate the clouds drifting across the sky.\",\n \"image\": {\n \"url\": `data:image/png;base64,${imageB64}`\n },\n \"duration\": 1,\n \"aspect_ratio\": \"16:9\",\n \"resolution\": \"480p\"\n};\n\nconst response = await fetch(\n \"https://api.cometapi.com/grok/v1/videos/generations\",\n {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.COMETAPI_KEY}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify(payload),\n },\n);\nif (!response.ok) throw new Error(`Request failed: ${response.status}`);\nconsole.log((await response.json()).request_id);" }, { "lang": "Shell", "label": "Reference image", "source": "curl https://api.cometapi.com/grok/v1/videos/generations \\\n -H \"Authorization: Bearer $COMETAPI_KEY\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary '{\n \"model\": \"grok-imagine-video-1.5\",\n \"prompt\": \"Use as the visual reference for a gentle cinematic pan.\",\n \"reference_images\": [\n {\n \"url\": \"https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png\"\n }\n ],\n \"duration\": 1,\n \"aspect_ratio\": \"16:9\",\n \"resolution\": \"720p\"\n}'" }, { "lang": "Python", "label": "Reference image", "source": "import os\nimport requests\n\npayload = {\n \"model\": \"grok-imagine-video-1.5\",\n \"prompt\": \"Use as the visual reference for a gentle cinematic pan.\",\n \"reference_images\": [\n {\n \"url\": \"https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png\"\n }\n ],\n \"duration\": 1,\n \"aspect_ratio\": \"16:9\",\n \"resolution\": \"720p\"\n}\n\nresponse = requests.post(\n \"https://api.cometapi.com/grok/v1/videos/generations\",\n headers={\n \"Authorization\": \"Bearer \" + os.environ[\"COMETAPI_KEY\"],\n \"Content-Type\": \"application/json\",\n },\n json=payload,\n timeout=180,\n)\nresponse.raise_for_status()\nprint(response.json()[\"request_id\"])" }, { "lang": "JavaScript", "label": "Reference image", "source": "const payload = {\n \"model\": \"grok-imagine-video-1.5\",\n \"prompt\": \"Use as the visual reference for a gentle cinematic pan.\",\n \"reference_images\": [\n {\n \"url\": \"https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png\"\n }\n ],\n \"duration\": 1,\n \"aspect_ratio\": \"16:9\",\n \"resolution\": \"720p\"\n};\n\nconst response = await fetch(\n \"https://api.cometapi.com/grok/v1/videos/generations\",\n {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.COMETAPI_KEY}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify(payload),\n },\n);\nif (!response.ok) throw new Error(`Request failed: ${response.status}`);\nconsole.log((await response.json()).request_id);" }, { "lang": "Shell", "label": "Reference image and preset voice", "source": "curl https://api.cometapi.com/grok/v1/videos/generations \\\n -H \"Authorization: Bearer $COMETAPI_KEY\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary '{\n \"model\": \"grok-imagine-video-1.5\",\n \"prompt\": \"Use as the visual reference while says Welcome to the observatory.\",\n \"reference_images\": [\n {\n \"url\": \"https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png\"\n }\n ],\n \"reference_audios\": [\n {\n \"voice_id\": \"eve\"\n }\n ],\n \"duration\": 1,\n \"aspect_ratio\": \"16:9\",\n \"resolution\": \"720p\"\n}'" }, { "lang": "Python", "label": "Reference image and preset voice", "source": "import os\nimport requests\n\npayload = {\n \"model\": \"grok-imagine-video-1.5\",\n \"prompt\": \"Use as the visual reference while says Welcome to the observatory.\",\n \"reference_images\": [\n {\n \"url\": \"https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png\"\n }\n ],\n \"reference_audios\": [\n {\n \"voice_id\": \"eve\"\n }\n ],\n \"duration\": 1,\n \"aspect_ratio\": \"16:9\",\n \"resolution\": \"720p\"\n}\n\nresponse = requests.post(\n \"https://api.cometapi.com/grok/v1/videos/generations\",\n headers={\n \"Authorization\": \"Bearer \" + os.environ[\"COMETAPI_KEY\"],\n \"Content-Type\": \"application/json\",\n },\n json=payload,\n timeout=180,\n)\nresponse.raise_for_status()\nprint(response.json()[\"request_id\"])" }, { "lang": "JavaScript", "label": "Reference image and preset voice", "source": "const payload = {\n \"model\": \"grok-imagine-video-1.5\",\n \"prompt\": \"Use as the visual reference while says Welcome to the observatory.\",\n \"reference_images\": [\n {\n \"url\": \"https://apidoc.cometapi.com/images/image/gemini/6100640_569429.png\"\n }\n ],\n \"reference_audios\": [\n {\n \"voice_id\": \"eve\"\n }\n ],\n \"duration\": 1,\n \"aspect_ratio\": \"16:9\",\n \"resolution\": \"720p\"\n};\n\nconst response = await fetch(\n \"https://api.cometapi.com/grok/v1/videos/generations\",\n {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.COMETAPI_KEY}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify(payload),\n },\n);\nif (!response.ok) throw new Error(`Request failed: ${response.status}`);\nconsole.log((await response.json()).request_id);" } ] } } } }