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

# Grok Videos Generation API 대결 설명

> Grok API guide - Ace Data Cloud

본 문서는 Grok Videos Generation API의 대결 설명을 소개하며, 입력 텍스트 프롬프트, 입력 이미지 및 선택적인 참조 이미지를 통해 Grok Imagine(xAI) 비디오를 생성할 수 있습니다.

## 신청 절차

Grok Videos Generation API를 사용하려면 먼저 [Ace Data Cloud 콘솔](https://platform.acedata.cloud/console/applications)에서 API Token을 받아야 하며, 이를 보관해 두십시오.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

로그인 또는 등록이 되어 있지 않은 경우 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 초대하며, 완료 후 현재 페이지로 자동으로 돌아옵니다.

**하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스마다 별도로 신청할 필요가 없습니다.** 최초 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족할 경우 [콘솔](https://platform.acedata.cloud/console/coin)에서 일반 잔액을 충전할 수 있습니다.

> 📘 전체 문서: [Grok Videos Generation API →](https://platform.acedata.cloud/documents/grok-videos)

## 모델 설명

본 API는 모델 이름의 접미사를 통해 상위 엔드포인트를 선택합니다: `:reverse`는 빠른/표준 엔드포인트(더 저렴함)를 사용하고, `:official`은 공식 엔드포인트(화질이 더 높고, 출력 초수에 따라 요금 부과)를 사용합니다. 총 네 가지 모델을 지원합니다:

* `grok-imagine-video-1.5-fast:reverse` (기본값): 문생 비디오(오직 `prompt`만 전달)와 그림생 비디오(`image_url` 전달)를 지원하며, 길이는 6–30초로, 길이에 따라 요금이 부과되며 가장 저렴합니다.
* `grok-imagine-video:reverse`: 문생 및 그림생 비디오를 지원하며, 길이는 1–15초로, 출력 초수에 따라 요금이 부과됩니다.
* `grok-imagine-video:official`: 공식 엔드포인트로, 문생 및 그림생 비디오를 지원하며, 길이는 1–15초로, 출력 초수에 따라 요금이 부과되며 화질이 더 높습니다.
* `grok-imagine-video-1.5:official`: 공식 엔드포인트로, **오직 그림생 비디오만 지원**하며, **반드시** `image_url`을 전달해야 하며, 길이는 1–15초로, 최대 `1080p`를 지원하며 출력 초수에 따라 요금이 부과됩니다.

## 기본 사용

먼저 기본 사용 방식을 이해하고, 입력 프롬프트 `prompt`, 모델 `model` 등의 매개변수를 입력하면 해당 비디오를 생성할 수 있습니다.

여기서 요청 헤더를 설정한 것을 볼 수 있습니다:

* `accept`: 어떤 형식의 응답 결과를 받고 싶은지, 여기서는 `application/json`으로 작성하여 JSON 형식으로 설정합니다.
* `authorization`: API를 호출하는 키로, 신청 후 바로 드롭다운에서 선택할 수 있습니다.

또한 요청 본문을 설정했습니다:

* `prompt`: 생성하고자 하는 비디오 내용에 대한 텍스트 프롬프트입니다. 문생 비디오를 만들 때 **필수**이며, `image_url`을 전달할 때는 선택 사항입니다.
* `model`: 비디오를 생성할 모델로, 선택할 수 있는 값은 `grok-imagine-video-1.5-fast:reverse` (기본값), `grok-imagine-video:reverse`, `grok-imagine-video:official` 또는 `grok-imagine-video-1.5:official`입니다.
* `image_url`: 그림생 비디오의 입력 이미지 링크입니다. `model`이 `grok-imagine-video-1.5:official`일 때 **필수**입니다.
* `reference_image_urls`: 비디오의 스타일이나 내용을 안내하기 위한 선택적 참조 이미지 링크 배열입니다.
* `aspect_ratio`: 생성할 비디오의 가로 세로 비율로, 선택할 수 있는 값은 `1:1` / `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3`입니다.
* `resolution`: 출력 해상도로, 선택할 수 있는 값은 `480p` (기본값), `720p` 또는 `1080p`입니다.
* `duration`: 생성할 비디오의 길이(초)입니다. `grok-imagine-video-1.5-fast:reverse`의 경우 6–30의 값을 가지며, 나머지 모델은 1–15의 값을 가집니다. 기본값은 6입니다. 6초 또는 10초를 사용하는 것이 추천되며, 이 두 표준 길이는 상대적으로 안정적입니다.
* `callback_url`: 비동기 콜백 주소로, 설정 후 API는 즉시 `task_id`를 반환하며, 작업이 완료되면 결과를 해당 주소로 POST합니다.
* `async`: 선택 사항으로, `true`로 설정하면 인터페이스가 즉시 `task_id`를 반환하며, `callback_url`을 제공할 필요가 없고, 이후 해당 작업 조회 인터페이스를 통해 결과를 폴링하여 얻을 수 있습니다.

"Try" 버튼을 클릭하면 테스트를 진행할 수 있으며, 얻은 결과는 다음과 유사합니다:

```json theme={null}
{
  "success": true,
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
  "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2",
  "data": [
    {
      "id": "grok-imagine-video-1.5-fast:reverse:41eb9a5f-3b2d-4d1e-9f5a-6c2f1a0b9e77",
      "video_url": "https://cdn.acedata.cloud/c8cbf53aa0.mp4",
      "state": "succeeded"
    }
  ]
}
```

반환 결과는 여러 필드를 포함하며, 다음과 같이 설명됩니다:

* `success`: 이번 비디오 생성 요청이 성공했는지 여부입니다.
* `task_id`: 이번 비디오 생성 작업의 ID입니다.
* `trace_id`: 이번 요청의 추적 ID로, 문제를 해결하는 데 사용됩니다.
* `data`: 생성된 비디오 결과 목록입니다.
  * `id`: 생성된 비디오의 고유 식별자입니다.
  * `video_url`: 생성된 비디오의 링크 주소입니다.
  * `state`: 비디오 생성 작업의 상태로, 선택할 수 있는 값은 `pending` / `succeeded` / `failed`입니다.

우리는 결과의 `data`에서 `video_url` 링크 주소를 통해 생성된 비디오를 가져오기만 하면 됩니다.

해당 CURL 코드는 다음과 같습니다:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/grok/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "resolution": "480p",
  "duration": 6
}'
```

해당 Python 코드는 다음과 같습니다:

```python theme={null}
import requests

url = "https://api.acedata.cloud/grok/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
    "model": "grok-imagine-video-1.5-fast:reverse",
    "resolution": "480p",
    "duration": 6
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

## 그림생 비디오

입력 이미지 기반으로 비디오를 생성하고 싶다면 `image_url`을 전달할 수 있습니다. `grok-imagine-video-1.5:official`을 사용할 때는 반드시 이 필드를 제공해야 합니다:

```json theme={null}
{
  "prompt": "The character slowly turns around and smiles at the camera",
  "model": "grok-imagine-video-1.5:official",
  "image_url": "https://cdn.acedata.cloud/5hmkdg.jpg",
  "resolution": "720p",
  "duration": 6
}
```

## 참조 이미지 안내

비디오의 스타일이나 내용을 안내하기 위해 하나 이상의 참조 이미지를 사용하고 싶다면 `reference_image_urls`에 이미지 링크 배열을 전달할 수 있습니다:

```json theme={null}
{
  "prompt": "A character dancing in the same art style",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "reference_image_urls": [
    "https://cdn.acedata.cloud/vunnjf.png"
  ]
}
```

## 비동기 콜백

비디오 생성에는 일정한 처리 시간이 필요합니다. 긴 연결을 유지하고 싶지 않다면 `callback_url`을 전달할 수 있으며, 이 경우 API는 즉시 `task_id`를 반환하고 작업이 완료되면 최종 결과를 해당 주소로 POST합니다:

```json theme={null}
{
  "prompt": "햇빛이 비치는 정원에서 나비를 쫓는 새끼 고양이의 영화 같은 장면",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "duration": 6,
  "callback_url": "https://your-domain.com/callback/grok"
}
```

즉시 반환된 결과는 다음과 같습니다:

```json theme={null}
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
```

## 작업 결과 조회

비동기 콜백을 사용했거나 작업 상태를 적극적으로 조회하고 싶다면 [Grok Tasks API](https://platform.acedata.cloud/documents/grok-tasks) (`POST https://api.acedata.cloud/grok/tasks`)를 통해 `task_id`에 따라 작업의 최신 상태와 결과를 조회할 수 있습니다.

## 요금 설명

본 서비스의 요금 방식은 `model`에 따라 결정됩니다:

* `grok-imagine-video-1.5-fast:reverse`: 시간에 따라 요금이 부과되며, 해상도와는 무관합니다 — `6–10` 초, `11–20` 초, `21–30` 초는 각각 다른 요금 구간에 해당합니다.
* `grok-imagine-video:reverse`: "출력 초수"에 따라 요금이 부과되며, 총 가격 = 단가 × `duration`입니다.
* `grok-imagine-video:official` 및 `grok-imagine-video-1.5:official`: 공식 엔드포인트로, "출력 초수"에 따라 요금이 부과되며, 해상도가 높을수록 단가가 높습니다; 공식 모델은 내용 검토에 실패하더라도 요금이 부과됩니다.

구체적인 단가는 가격 페이지를 기준으로 합니다. 실패한 요청은 요금이 부과되지 않으며 무료 한도를 차지하지 않습니다.

## 오류 처리

요청에 문제가 발생할 경우, API는 해당 오류 코드와 설명을 반환하며, 일반적인 오류는 다음과 같습니다:

* `400`: 요청 매개변수가 잘못되었습니다. 예를 들어 비디오 생성에 `prompt`가 누락되었거나, `grok-imagine-video-1.5:official`에 `image_url`이 누락되었거나, `duration`이 범위를 초과했습니다 (`grok-imagine-video-1.5-fast:reverse`는 6–30, 나머지 모델은 1–15).
* `401`: 인증 실패, 토큰이 유효하지 않거나 API와 일치하지 않습니다.
* `403`: 잔액 부족 또는 프롬프트가 내용 검토에 의해 거부되었습니다.
* `429`: 요청이 너무 빈번합니다. 잠시 후 다시 시도하십시오.
* `500`: 비디오 생성 실패 또는 서비스 이상.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.