{
  "openapi": "3.1.0",
  "info": {
    "title": "Video Generation API",
    "version": "1.0.0",
    "description": "Create an asynchronous xAI Grok image-to-video job and poll it later with GET /grok/v1/videos/{request_id}."
  },
  "servers": [
    {
      "url": "https://api.cometapi.com"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Bearer token authentication. Use your CometAPI key."
      }
    }
  },
  "paths": {
    "/grok/v1/videos/generations": {
      "post": {
        "summary": "Create an xAI video generation job",
        "operationId": "video_generation",
        "description": "Start a Grok image-to-video job from a prompt and one source image. Save the returned request_id and poll the query endpoint until the provider status becomes done.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "prompt"
                ],
                "properties": {
                  "prompt": {
                    "type": "string",
                    "description": "Prompt describing how the source image should animate. CometAPI requires this field for this route.",
                    "example": "Animate the still image with a slow camera move and natural motion."
                  },
                  "aspect_ratio": {
                    "type": "string",
                    "description": "Output aspect ratio. Combine with resolution to choose the target frame; for example 480p with 1:1 targets 480x480, 720p with 16:9 targets 1280x720, and 720p with 9:16 targets 720x1280. This endpoint does not expose an exact size field.",
                    "enum": [
                      "1:1",
                      "16:9",
                      "9:16",
                      "4:3",
                      "3:4",
                      "3:2",
                      "2:3"
                    ]
                  },
                  "duration": {
                    "type": "integer",
                    "description": "Output duration in seconds. Use an integer from 1 through 15. If omitted, CometAPI treats the request as an 8-second generation for billing and default handling.",
                    "default": 8
                  },
                  "image": {
                    "type": "object",
                    "required": [
                      "url"
                    ],
                    "properties": {
                      "url": {
                        "type": "string",
                        "description": "Public image URL or data URI such as data:image/png;base64,<BASE64_IMAGE_DATA>."
                      }
                    },
                    "description": "Source image for image-to-video. Use a public JPEG, PNG, or WebP URL, or a data URI such as data:image/png;base64,<BASE64_IMAGE_DATA>."
                  },
                  "model": {
                    "type": "string",
                    "description": "xAI video model id. The default example uses Grok Imagine 1.5 for image-to-video.",
                    "default": "grok-imagine-video-1.5",
                    "example": "grok-imagine-video-1.5"
                  },
                  "output": {
                    "type": "object",
                    "properties": {
                      "upload_url": {
                        "type": "string",
                        "description": "Optional signed URL for uploading the finished result to your own storage."
                      }
                    }
                  },
                  "resolution": {
                    "type": "string",
                    "description": "Output resolution. Use 720p for a small image-to-video test, or 1080p when you need a higher resolution tier.",
                    "enum": [
                      "480p",
                      "720p",
                      "1080p"
                    ],
                    "default": "720p"
                  },
                  "size": {
                    "type": "string",
                    "description": "Deprecated size field. Prefer aspect_ratio and resolution."
                  },
                  "user": {
                    "type": "string",
                    "description": "Optional end-user identifier."
                  }
                },
                "default": {
                  "model": "grok-imagine-video-1.5",
                  "prompt": "Animate the still image with a slow camera move and natural motion.",
                  "image": {
                    "url": "https://your-image-host/source.jpg"
                  },
                  "duration": 1,
                  "aspect_ratio": "16:9",
                  "resolution": "720p"
                }
              },
              "examples": {
                "Image URL": {
                  "summary": "Image URL",
                  "value": {
                    "model": "grok-imagine-video-1.5",
                    "prompt": "Animate the still image with a slow camera move and natural motion.",
                    "image": {
                      "url": "https://your-image-host/source.jpg"
                    },
                    "duration": 1,
                    "aspect_ratio": "16:9",
                    "resolution": "720p"
                  }
                },
                "Data URI": {
                  "summary": "Data URI",
                  "value": {
                    "model": "grok-imagine-video-1.5",
                    "prompt": "Animate the clouds drifting across the sky.",
                    "image": {
                      "url": "data:image/png;base64,<BASE64_IMAGE_DATA>"
                    },
                    "duration": 1,
                    "aspect_ratio": "16:9",
                    "resolution": "720p"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "request_id"
                  ],
                  "properties": {
                    "request_id": {
                      "type": "string",
                      "description": "Deferred request id used for polling."
                    }
                  },
                  "example": {
                    "request_id": "<request_id>"
                  }
                },
                "example": {
                  "request_id": "<request_id>"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "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  -d '{\n    \"model\": \"grok-imagine-video-1.5\",\n    \"prompt\": \"Animate the still image with a slow camera move and natural motion.\",\n    \"image\": {\"url\": \"https://your-image-host/source.jpg\"},\n    \"duration\": 1,\n    \"aspect_ratio\": \"16:9\",\n    \"resolution\": \"720p\"\n  }'\n"
          },
          {
            "lang": "Shell",
            "label": "Data URI",
            "source": "IMAGE_B64=$(base64 < source.png | tr -d '\\n')\n\ncurl https://api.cometapi.com/grok/v1/videos/generations \\\n  -H \"Authorization: Bearer $COMETAPI_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  --data-binary @- <<EOF\n{\n  \"model\": \"grok-imagine-video-1.5\",\n  \"prompt\": \"Animate the clouds drifting across the sky.\",\n  \"image\": {\"url\": \"data:image/png;base64,${IMAGE_B64}\"},\n  \"duration\": 1,\n  \"aspect_ratio\": \"16:9\",\n  \"resolution\": \"720p\"\n}\nEOF\n"
          },
          {
            "lang": "Python",
            "label": "Image URL",
            "source": "import os\nimport requests\n\nresponse = requests.post(\n    \"https://api.cometapi.com/grok/v1/videos/generations\",\n    headers={\"Authorization\": \"Bearer \" + os.environ[\"COMETAPI_KEY\"]},\n    json={\n        \"model\": \"grok-imagine-video-1.5\",\n        \"prompt\": \"Animate the still image with a slow camera move and natural motion.\",\n        \"image\": {\"url\": \"https://your-image-host/source.jpg\"},\n        \"duration\": 1,\n        \"aspect_ratio\": \"16:9\",\n        \"resolution\": \"720p\",\n    },\n)\n\ntask = response.json()\nprint(task[\"request_id\"])  # poll GET /grok/v1/videos/{request_id}\n"
          },
          {
            "lang": "Python",
            "label": "Data URI",
            "source": "import base64\nimport os\nimport requests\n\nwith open(\"source.png\", \"rb\") as f:\n    image_b64 = base64.b64encode(f.read()).decode()\n\nresponse = requests.post(\n    \"https://api.cometapi.com/grok/v1/videos/generations\",\n    headers={\"Authorization\": \"Bearer \" + os.environ[\"COMETAPI_KEY\"]},\n    json={\n        \"model\": \"grok-imagine-video-1.5\",\n        \"prompt\": \"Animate the clouds drifting across the sky.\",\n        \"image\": {\"url\": \"data:image/png;base64,\" + image_b64},\n        \"duration\": 1,\n        \"aspect_ratio\": \"16:9\",\n        \"resolution\": \"720p\",\n    },\n)\n\ntask = response.json()\nprint(task[\"request_id\"])\n"
          },
          {
            "lang": "JavaScript",
            "label": "Image URL",
            "source": "const response = await fetch(\"https://api.cometapi.com/grok/v1/videos/generations\", {\n    method: \"POST\",\n    headers: {\n        Authorization: `Bearer ${process.env.COMETAPI_KEY}`,\n        \"Content-Type\": \"application/json\",\n    },\n    body: JSON.stringify({\n        model: \"grok-imagine-video-1.5\",\n        prompt: \"Animate the still image with a slow camera move and natural motion.\",\n        image: { url: \"https://your-image-host/source.jpg\" },\n        duration: 1,\n        aspect_ratio: \"16:9\",\n        resolution: \"720p\",\n    }),\n});\n\nconst task = await response.json();\nconsole.log(task.request_id); // poll GET /grok/v1/videos/{request_id}\n"
          },
          {
            "lang": "JavaScript",
            "label": "Data URI",
            "source": "import { readFile } from \"node:fs/promises\";\n\nconst imageB64 = (await readFile(\"source.png\")).toString(\"base64\");\n\nconst response = await fetch(\"https://api.cometapi.com/grok/v1/videos/generations\", {\n    method: \"POST\",\n    headers: {\n        Authorization: `Bearer ${process.env.COMETAPI_KEY}`,\n        \"Content-Type\": \"application/json\",\n    },\n    body: JSON.stringify({\n        model: \"grok-imagine-video-1.5\",\n        prompt: \"Animate the clouds drifting across the sky.\",\n        image: { url: `data:image/png;base64,${imageB64}` },\n        duration: 1,\n        aspect_ratio: \"16:9\",\n        resolution: \"720p\",\n    }),\n});\n\nconst task = await response.json();\nconsole.log(task.request_id);\n"
          }
        ]
      }
    }
  }
}