> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# xAI 비디오 생성

> CometAPI POST /grok/v1/videos/generations를 사용해 입력 이미지와 프롬프트로 Grok image-to-video 작업을 생성한 다음, request_id로 결과를 폴링합니다.

이 엔드포인트를 사용하면 하나의 소스 이미지와 프롬프트로 Grok image-to-video 작업을 시작할 수 있습니다. `request_id`가 즉시 반환되므로 비동기 워크플로의 첫 단계로 다루어야 합니다.

## 작은 요청으로 시작하기

* `model: grok-imagine-video-1.5` 사용
* `image.url`을 공개된 JPEG, PNG 또는 WebP URL로 설정
* 첫 요청에서는 `duration`을 `1`, `resolution`을 `720p`로 유지
* 애니메이션 방향이 분명하도록 `prompt`를 구체적으로 작성
* base64를 보낼 경우 문서와 OpenAPI 예시 형식은 `data:image/png;base64,<BASE64_IMAGE_DATA>`로 유지

## 기간과 해상도

| 설정             | 지원 값                            | 기본값          | 경계 동작                                                                                     |
| -------------- | ------------------------------- | ------------ | ----------------------------------------------------------------------------------------- |
| `duration`     | 정수 `1`-`15`                     | `8`          | 첫 테스트에는 더 짧은 클립을 사용하세요. 더 긴 클립은 비용이 더 많이 들고 완료까지 시간이 더 걸립니다.                              |
| `resolution`   | `480p`, `720p`, `1080p`         | 예시에서는 `720p` | 해상도가 높은 요청일수록 비용이 더 많이 들고 완료까지 시간이 더 걸립니다.                                                |
| `aspect_ratio` | `1:1`, `16:9`, `9:16` 같은 비율 레이블 | 예시에서는 `16:9` | 이 엔드포인트는 `resolution`과 `aspect_ratio`를 함께 사용합니다. 정확한 `WxH` 제어를 위한 별도의 `size` 필드는 보내지 마세요. |

| 요청 조합                                    | 예상 출력 `WxH` |
| ---------------------------------------- | ----------- |
| `resolution: 480p`, `aspect_ratio: 1:1`  | `480x480`   |
| `resolution: 720p`, `aspect_ratio: 16:9` | `1280x720`  |
| `resolution: 720p`, `aspect_ratio: 9:16` | `720x1280`  |

## 작업 흐름

<Steps>
  <Step title="작업 생성">
    프롬프트와 소스 이미지를 전송한 다음, 반환된 `request_id`를 저장합니다.
  </Step>

  <Step title="완료될 때까지 폴링">
    중첩된 provider status가 `done`이 될 때까지 [xAI 비디오 결과 가져오기](./get-video-generation-results)를 호출합니다.
  </Step>

  <Step title="출력 저장">
    provider의 임시 전달 기간이 지난 뒤에도 필요하다면 최종 `video.url`을 자체 스토리지에 복사합니다.
  </Step>
</Steps>


## OpenAPI

````yaml api/openapi/video/xai/post-video-generation.openapi.json POST /grok/v1/videos/generations
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: []
paths:
  /grok/v1/videos/generations:
    post:
      summary: Create an xAI video generation job
      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.
      operationId: video_generation
      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 \
              -H "Authorization: Bearer $COMETAPI_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "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"
              }'
        - lang: Shell
          label: Data URI
          source: |
            IMAGE_B64=$(base64 < source.png | tr -d '\n')

            curl https://api.cometapi.com/grok/v1/videos/generations \
              -H "Authorization: Bearer $COMETAPI_KEY" \
              -H "Content-Type: application/json" \
              --data-binary @- <<EOF
            {
              "model": "grok-imagine-video-1.5",
              "prompt": "Animate the clouds drifting across the sky.",
              "image": {"url": "data:image/png;base64,${IMAGE_B64}"},
              "duration": 1,
              "aspect_ratio": "16:9",
              "resolution": "720p"
            }
            EOF
        - lang: Python
          label: Image URL
          source: |
            import os
            import requests

            response = requests.post(
                "https://api.cometapi.com/grok/v1/videos/generations",
                headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
                json={
                    "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",
                },
            )

            task = response.json()
            print(task["request_id"])  # poll GET /grok/v1/videos/{request_id}
        - lang: Python
          label: Data URI
          source: |
            import base64
            import os
            import requests

            with open("source.png", "rb") as f:
                image_b64 = base64.b64encode(f.read()).decode()

            response = requests.post(
                "https://api.cometapi.com/grok/v1/videos/generations",
                headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
                json={
                    "model": "grok-imagine-video-1.5",
                    "prompt": "Animate the clouds drifting across the sky.",
                    "image": {"url": "data:image/png;base64," + image_b64},
                    "duration": 1,
                    "aspect_ratio": "16:9",
                    "resolution": "720p",
                },
            )

            task = response.json()
            print(task["request_id"])
        - lang: JavaScript
          label: Image URL
          source: >
            const response = await
            fetch("https://api.cometapi.com/grok/v1/videos/generations", {
                method: "POST",
                headers: {
                    Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
                    "Content-Type": "application/json",
                },
                body: JSON.stringify({
                    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",
                }),
            });


            const task = await response.json();

            console.log(task.request_id); // poll GET
            /grok/v1/videos/{request_id}
        - lang: JavaScript
          label: Data URI
          source: >
            import { readFile } from "node:fs/promises";


            const imageB64 = (await readFile("source.png")).toString("base64");


            const response = await
            fetch("https://api.cometapi.com/grok/v1/videos/generations", {
                method: "POST",
                headers: {
                    Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
                    "Content-Type": "application/json",
                },
                body: JSON.stringify({
                    model: "grok-imagine-video-1.5",
                    prompt: "Animate the clouds drifting across the sky.",
                    image: { url: `data:image/png;base64,${imageB64}` },
                    duration: 1,
                    aspect_ratio: "16:9",
                    resolution: "720p",
                }),
            });


            const task = await response.json();

            console.log(task.request_id);
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication. Use your CometAPI key.

````