Grok 이미지-비디오 API 사용법 (단계별 가이드)

세 줄 요약

그록 이미지-투-비디오 API는 grok-imagine-video 모델을 사용하여 정적 이미지를 비디오 클립으로 애니메이션화합니다. 이미지 URL, 프롬프트 및 선택적 설정을 https://api.x.ai/v1/videos/generations으로 POST합니다. API는 즉시 request_id를 반환합니다. 그런 다음 status가 "done"이 될 때까지 GET /v1/videos/{request_id}를 폴링합니다. 재생 시간은 1초에서 15초까지 가능합니다. 480p 출력의 경우 초당 0.05달러부터 요금이 시작됩니다.

소개

2026년 1월 28일, xAI는 grok-imagine-video 모델을 공개 API로 출시했습니다. 첫 달 동안 이 모델은 12억 개의 비디오를 생성했으며 Artificial Analysis 텍스트-투-비디오 순위표에서 1위를 차지했습니다. 이미지-투-비디오는 주력 기능 중 하나입니다. API에 사진과 설명적인 프롬프트를 제공하면 사진을 짧은 비디오 클립으로 애니메이션화하여 MP4로 다운로드할 수 있도록 합니다.

작업을 제출한 다음 완료를 폴링하는 이러한 비동기 흐름은 많은 개발자가 간과하는 테스트 문제를 야기합니다. 첫 번째 POST가 200을 반환했을 때 통합이 완료된 것이 아닙니다. 폴링 루프가 실제 네트워크 조건에서 "processing", "done", "failed" 상태를 올바르게 처리하는지 확인해야 완료된 것입니다.

Apidog의 테스트 시나리오(Test Scenarios)는 이 문제를 직접 해결합니다. /v1/videos/generations로 POST하고, request_id를 추출하고, status == "done"이 될 때까지 폴링 요청을 반복한 다음, 비디오 URL이 존재하는지 검증하는 연결된 시퀀스를 구축할 수 있습니다. 이 가이드의 나중에 나오는 테스트 연습을 따라하려면 Apidog를 무료로 다운로드하세요.

버튼

그록 이미지-투-비디오 API란 무엇인가요?

그록 이미지-투-비디오 API는 xAI의 비디오 생성 제품의 일부입니다. grok-imagine-video 모델에 속하며, 이미지를 출력 비디오의 시작 프레임으로 받아들입니다. 모델은 이미지 내용과 텍스트 프롬프트를 분석한 다음, 장면을 애니메이션화하기 위한 자연스러운 움직임을 생성합니다.

API 엔드포인트는 다음과 같습니다:

POST https://api.x.ai/v1/videos/generations

인증은 표준 Bearer 토큰을 사용합니다:

Authorization: Bearer YOUR_XAI_API_KEY

키는 xAI 콘솔에서 얻을 수 있습니다. 동일한 API는 텍스트-투-비디오(image 매개변수 생략), 비디오 확장 및 비디오 편집도 지원합니다.

이미지-투-비디오 프로세스 작동 방식

요청 본문의 image 매개변수는 출력 비디오의 첫 번째 프레임을 지정합니다. 모델은 이미지를 교체하지 않습니다. 이미지에서 시작합니다. 첫 번째 프레임의 모든 픽셀은 원본 이미지에서 가져옵니다. 그런 다음 모델은 프롬프트를 기반으로 해당 장면이 시간상 어떻게 움직일지 예측합니다.

예를 들어, 일출 시 산 호수 사진을 제공합니다. 프롬프트는 "아침 안개가 드리워지며 잔잔한 물결이 수면에 퍼진다"입니다. 출력 비디오의 첫 번째 프레임은 제공한 사진입니다. 이후 프레임은 프롬프트에 따라 물과 안개가 움직이는 것을 보여줍니다.

이는 모델 자체가 첫 번째 프레임을 생성하는 텍스트-투-비디오와는 다릅니다. 이미지-투-비디오는 시작 장면에 대한 정확한 제어를 제공합니다.

다음과 같은 경우 이미지-투-비디오를 선택해야 합니다:

움직임을 부여하고 싶은 기존 제품 사진, 풍경, 인물 사진이 있을 때.
첫 번째 프레임에서 브랜드 자산에 일관된 시각적 아이덴티티가 필요할 때.
움직임이 실제 또는 특정 장면에 기반을 둔 것처럼 느껴지기를 원할 때.

다음과 같은 경우 텍스트-투-비디오를 선택해야 합니다:

참조 이미지 없이 시각적 아이디어를 탐색할 때.
모델이 장면 구성을 전적으로 결정하기를 원할 때.
첫 번째 프레임의 정밀도보다 반복 속도가 더 중요할 때.

전제 조건

첫 호출을 하기 전에 다음이 필요합니다:

console.x.ai에 있는 xAI 계정.
xAI 콘솔에서 얻은 API 키. 이 키는 하드코딩하지 말고 환경 변수에 보관하세요.
Python 3.8+ 또는 Node.js 18+ (이 가이드의 예제는 둘 다 사용).
공개적으로 액세스 가능한 이미지 URL 또는 데이터 URI로 Base64로 인코딩된 이미지.

키를 환경 변수로 설정합니다:

export XAI_API_KEY="your_key_here"

상위 수준 클라이언트가 필요하면 xAI Python SDK를 설치합니다:

pip install xai-sdk

순수 HTTP 호출의 경우, requests (Python) 또는 fetch (Node.js) 외에 추가 패키지는 필요하지 않습니다.

첫 번째 이미지-투-비디오 요청하기

curl 사용

curl -X POST https://api.x.ai/v1/videos/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "Gentle waves move across the surface, morning mist rises slowly",
    "image": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1a/24701-nature-natural-beauty.jpg/1280px-24701-nature-natural-beauty.jpg"
    },
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

응답은 request_id와 함께 즉시 돌아옵니다:

{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}

비디오는 아직 준비되지 않았습니다. 생성은 xAI 인프라에서 비동기적으로 발생합니다. 결과를 폴링해야 합니다.

Python 사용 (순수 요청)

import os
import requests

api_key = os.environ["XAI_API_KEY"]

payload = {
    "model": "grok-imagine-video",
    "prompt": "Gentle waves move across the surface, morning mist rises slowly",
    "image": {
        "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1a/24701-nature-natural-beauty.jpg/1280px-24701-nature-natural-beauty.jpg"
    },
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9"
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.x.ai/v1/videos/generations",
    json=payload,
    headers=headers
)

data = response.json()
request_id = data["request_id"]
print(f"Job started: {request_id}")

Base64 이미지 사용

이미지가 로컬에 있거나 공개적으로 액세스할 수 없는 경우, 데이터 URI로 인코딩합니다:

import base64

with open("my_image.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

payload["image"] = {
    "url": f"data:image/jpeg;base64,{encoded}"
}

결과 폴링하기

비디오 생성은 비동기적입니다. API는 비디오가 xAI 서버에서 렌더링되는 동안 request_id를 반환합니다. 상태 엔드포인트를 폴링해야 합니다:

GET https://api.x.ai/v1/videos/{request_id}

상태 필드는 다음 값들을 통해 이동합니다:

상태	의미
`"processing"`	비디오가 여전히 렌더링 중입니다.
`"done"`	비디오가 준비되었으며, 응답에 URL이 있습니다.
`"failed"`	문제가 발생했습니다.

완료된 응답은 다음과 같습니다:

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/....mp4",
    "duration": 6
  },
  "progress": 100
}

전체 Python 폴링 루프

import time

def poll_video(request_id: str, api_key: str, interval: int = 5) -> dict:
    url = f"https://api.x.ai/v1/videos/{request_id}"
    headers = {"Authorization": f"Bearer {api_key}"}

    while True:
        response = requests.get(url, headers=headers)
        data = response.json()
        status = data.get("status")

        print(f"Status: {status} | Progress: {data.get('progress', 0)}%")

        if status == "done":
            return data["video"]
        elif status == "failed":
            raise RuntimeError(f"Video generation failed for {request_id}")

        time.sleep(interval)

# 사용법
video = poll_video(request_id, api_key)
print(f"Video URL: {video['url']}")
print(f"Duration: {video['duration']}s")

폴링 간격은 5초 이상으로 유지하십시오. API에는 분당 60회(초당 1회)의 요청 제한이 있습니다. 여러 작업을 동시에 빠르게 폴링하면 이 예산을 빠르게 소진할 수 있습니다.

xAI Python SDK 사용

xai-sdk 라이브러리는 비동기 패턴을 래핑합니다. client.video.generate()는 작업을 제출하고 비디오가 준비될 때까지 차단되며, 모든 폴링을 내부적으로 처리합니다:

from xai_sdk import Client
import os

client = Client(api_key=os.environ["XAI_API_KEY"])

video = client.video.generate(
    model="grok-imagine-video",
    prompt="Gentle waves move across the surface, morning mist rises slowly",
    image={"url": "https://example.com/landscape.jpg"},
    duration=6,
    resolution="720p",
    aspect_ratio="16:9"
)

print(f"Video URL: {video.url}")
print(f"Duration: {video.duration}s")

SDK는 폴링 루프, 상태 확인 및 오류 전파를 처리합니다. 직접 HTTP 폴링을 관리하지 않고 깔끔한 애플리케이션 코드를 원할 때 이 접근 방식을 사용하십시오.

폴링 간격, 재시도 전략 또는 로깅에 대한 세밀한 제어를 원할 경우, 순수 요청(raw requests) 방식이 더 많은 유연성을 제공합니다.

해상도, 재생 시간 및 화면 비율 제어

그록 비디오 API는 출력 형식에 대한 직접적인 제어를 제공합니다.

재생 시간

duration 매개변수는 1초에서 15초까지의 정수를 허용합니다. 기본값은 6초입니다.

"duration": 10

비디오가 길수록 비용이 더 많이 듭니다. 10초 클립은 동일한 해상도에서 1초 클립보다 대략 10배 더 비쌉니다.

해상도

두 가지 옵션이 있습니다:

값	설명
`"480p"`	기본값. 저렴한 비용, 빠른 생성.
`"720p"`	고품질. 초당 0.05달러 대신 초당 0.07달러.

"resolution": "720p"

화면 비율

aspect_ratio 매개변수는 출력 프레임 치수를 제어합니다:

값	사용 사례
`"16:9"`	기본값. 풍경 장면에 적합한 와이드스크린.
`"9:16"`	모바일 또는 소셜 스토리용 세로.
`"1:1"`	인스타그램 또는 소셜 썸네일용 정사각형.
`"4:3"`	클래식 사진 또는 프리젠테이션 형식.
`"3:4"`	인물 사진.
`"3:2"`	표준 사진 자르기.
`"2:3"`	세로 인물 형식.

image를 제공하면 화면 비율은 원본 이미지의 치수에 맞춰 기본 설정됩니다. 명시적으로 설정하여 재정의하거나 자를 수 있습니다.

스타일 지정을 위한 참조 이미지 사용

reference_images 매개변수는 image 매개변수와 다릅니다. 이 차이를 이해하는 것이 중요합니다.

image: 비디오의 첫 번째 프레임이 되는 원본 사진. 모델은 이 시작점에서 애니메이션을 만듭니다.

reference_images: 생성된 비디오의 스타일, 내용 또는 시각적 컨텍스트를 안내하는 최대 7개의 이미지 배열입니다. 이들은 출력의 프레임이 아닙니다. 모델이 움직임과 모양을 렌더링하는 방식에 영향을 미칩니다.

출력 비디오가 기존 자산의 시각적 특성을 채택하기를 원하지만 시작 프레임으로 사용하지 않을 때 reference_images를 사용하십시오:

{
  "model": "grok-imagine-video",
  "prompt": "A product rotating slowly on a clean white surface",
  "image": {
    "url": "https://example.com/product-shot.jpg"
  },
  "reference_images": [
    {"url": "https://example.com/brand-style-reference-1.jpg"},
    {"url": "https://example.com/lighting-reference.jpg"}
  ],
  "duration": 6,
  "resolution": "720p"
}

이 예에서 product-shot.jpg는 첫 번째 프레임입니다. 참조 이미지는 조명 및 스타일 처리 방식을 안내합니다.

첫 프레임 이미지가 전혀 없이 참조 이미지를 제공할 수도 있습니다. 이 경우 모델은 참조 이미지에서 스타일 안내를 받아 텍스트-투-비디오 출력을 생성합니다.

비디오 확장 및 편집

API는 초기 생성 외에 두 가지 추가 작업을 지원합니다.

비디오 확장

POST /v1/videos/extensions는 기존 비디오를 가져와 중단된 지점부터 추가적인 비디오를 생성합니다. 이는 15초의 호출당 제한 내에서 여러 생성 단계를 통해 더 긴 클립을 만드는 데 유용합니다.

curl -X POST https://api.x.ai/v1/videos/extensions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "video_id": "your_original_request_id",
    "prompt": "The mist continues to lift as sunlight breaks through",
    "duration": 5
  }'

응답은 동일한 비동기 패턴을 따릅니다: 확장된 클립을 위해 GET /v1/videos/{request_id}를 폴링합니다.

비디오 편집

POST /v1/videos/edits는 기존 비디오에 프롬프트 안내 수정을 적용합니다. 처음부터 다시 생성하지 않고도 내용이나 움직임의 특정 측면을 변경할 수 있습니다.

curl -X POST https://api.x.ai/v1/videos/edits \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "video_id": "your_original_request_id",
    "prompt": "Change the sky to a dramatic sunset with deep orange tones"
  }'

확장과 편집 모두 비동기적이며 동일한 폴링 패턴을 사용합니다.

가격 분석: 10초 비디오 비용

xAI 비디오 API는 두 가지 구성 요소에 대해 요금을 청구합니다: 입력 이미지 처리 및 출력 비디오 재생 시간.

구성 요소	비용
입력 이미지	이미지당 $0.002
480p 출력	초당 $0.05
720p 출력	초당 $0.07

예시: 720p 10초 비디오

입력 이미지: $0.002
출력: 10초 × $0.07 = $0.70
총계: $0.702

예시: 480p 6초 비디오 (기본 설정)

입력 이미지: $0.002
출력: 6초 × $0.05 = $0.30
총계: $0.302

입력 이미지 요금은 동일한 이미지 URL을 재사용하더라도 생성 요청을 제출할 때마다 적용됩니다. 동일한 기본 이미지를 반복해서 사용한다면 생성 호출을 적절하게 계획하십시오.

텍스트-투-비디오(image 매개변수 없음)는 $0.002 입력 요금이 면제되지만, 그 외에는 동일한 초당 요금 정책을 따릅니다.

Apidog로 그록 비디오 API 통합을 테스트하는 방법

비동기 패턴은 단순한 일회성 요청 테스트로는 다룰 수 없는 테스트 과제를 생성합니다. 다음 사항을 확인해야 합니다:

생성 요청이 request_id를 반환하는지.
폴링 요청이 대기하는 동안 "processing" 상태를 올바르게 처리하는지.
최종 응답에 status == "done"이 있고 비어 있지 않은 비디오 URL이 있는지.

Apidog의 테스트 시나리오(Test Scenarios)는 이러한 단계를 하나의 자동화된 흐름으로 연결합니다. 구축 방법은 다음과 같습니다:

단계 1: 새 테스트 시나리오 생성

Apidog에서 테스트 모듈을 열고 + 버튼을 클릭하여 새 시나리오를 생성합니다. 이름을 "Grok 이미지-투-비디오 비동기 흐름"으로 지정합니다.

단계 2: 생성 요청 추가

사용자 지정 POST 요청 단계를 추가합니다:

URL: https://api.x.ai/v1/videos/generations
메서드: POST
헤더: Authorization: Bearer {{xai_api_key}}
본문 (JSON):

{
  "model": "grok-imagine-video",
  "prompt": "Gentle mist rises from the water as light filters through the trees",
  "image": {
    "url": "https://example.com/your-test-image.jpg"
  },
  "duration": 6,
  "resolution": "480p"
}

단계 3: request_id 추출

POST 단계 후 변수 추출(Extract Variable) 프로세서를 추가합니다. 다음과 같이 구성합니다:

변수 이름: video_request_id
소스: 응답 본문
추출 방법: JSONPath
JSONPath 표현식: $.request_id

Apidog는 추출된 값을 {{video_request_id}}에 저장하여 이후 단계에서 사용할 수 있도록 합니다.

단계 4: 폴링 루프 구축

For 루프 프로세서를 추가합니다. 루프 안에 폴링 요청을 추가합니다:

URL: https://api.x.ai/v1/videos/{{video_request_id}}
메서드: GET
헤더: Authorization: Bearer {{xai_api_key}}

루프 안에 변수 추출(Extract Variable) 프로세서를 추가하여 현재 상태를 캡처합니다:

변수 이름: video_status
JSONPath: $.status

상태 추출 후 대기(Wait) 프로세서(5000ms)를 추가하여 요청 제한에 도달하는 것을 방지합니다.

루프의 다음 조건이면 중단(Break If) 조건을 {{video_status}} == "done"으로 설정합니다.

단계 5: 비디오 URL 검증

For 루프 후, 동일한 폴링 엔드포인트에 마지막 GET 단계를 추가합니다. 검증(Assertion) 프로세서를 추가합니다:

필드: $.video.url
조건: 비어 있지 않음

이 검증은 테스트가 통과하기 전에 비디오 URL이 존재하는지 확인합니다.

Apidog로 비동기 API를 테스트하는 방법에 대한 자세한 내용은, 더 복잡한 폴링 패턴 및 CI/CD 통합을 포함하여, 해당 전용 가이드를 참조하십시오.

시나리오 실행

테스트 시나리오 보기에서 실행(Run)을 클릭합니다. Apidog는 POST를 실행하고, request_id를 추출하며, status == "done"이 될 때까지 폴링을 반복한 다음, 검증을 평가합니다. 테스트 보고서는 각 단계의 상태와 타이밍을 보여줍니다.

Apidog CLI를 사용하여 이 시나리오를 CI/CD 파이프라인에 연결할 수 있습니다:

apidog run --scenario grok-video-async-flow --env production

일반적인 오류 및 해결 방법

401 권한 없음 (Unauthorized)

API 키가 없거나 유효하지 않습니다. Authorization 헤더 형식: Bearer YOUR_XAI_API_KEY를 확인하십시오. xAI 콘솔에서 키가 활성화되어 있는지 확인하십시오.

422 처리할 수 없는 엔티티 (Unprocessable Entity)

요청 본문 형식이 잘못되었습니다. 일반적인 원인: model 필드가 없거나, prompt가 비어 있거나, image.url에 액세스할 수 없습니다. 사용하기 전에 브라우저에서 이미지 URL을 테스트하십시오.

이미지 URL에 액세스할 수 없음

xAI 서버는 생성 시 이미지 URL을 가져올 수 있어야 합니다. 비공개 URL, 로컬호스트 주소 또는 인증 뒤의 URL은 실패합니다. 대신 공개 CDN 또는 Base64 데이터 URI를 사용하십시오.

상태가 "처리 중(processing)"에 무한정 머무르는 경우

생성은 해상도와 재생 시간에 따라 30초에서 몇 분까지 걸릴 수 있습니다. 상태가 10분 이상 "processing"에 머무르면 작업이 중단되었을 수 있습니다. 새 요청을 제출하십시오. xAI API는 현재 "failed"와 별도로 시간 초과 신호를 노출하지 않습니다.

요청 제한 오류 (429)

API는 분당 60회, 초당 1회의 요청을 허용합니다. 여러 작업을 동시에 폴링하는 경우 요청 간격을 두십시오. 최소한 폴링 호출 사이에 time.sleep(1)을 추가하십시오.

Base64 업로드 거부됨

데이터 URI에 올바른 MIME 타입 접두사가 포함되어 있는지 확인하십시오. JPEG 파일의 경우 data:image/jpeg;base64,를, PNG 파일의 경우 data:image/png;base64,를 사용하십시오.

화면 비율 불일치

원본 이미지의 비율과 현저히 다른 명시적인 aspect_ratio를 설정하면 모델이 잘라내거나 레터박스를 추가할 수 있습니다. 최상의 결과를 위해 화면 비율을 원본 이미지에 맞추십시오.

결론

그록 이미지-투-비디오 API는 정적 사진에서 짧은 애니메이션 클립까지 직접적인 경로를 제공합니다. 이미지를 POST하고 프롬프트를 제공한 다음, request_id를 받아 완료될 때까지 폴링하고 MP4를 다운로드합니다. grok-imagine-video 모델은 2026년 1월 Artificial Analysis 순위표에서 상위권을 차지했습니다. 한 달 동안 10억 개 이상의 비디오가 생성되었습니다. 이 규모는 기본 모델의 역량을 반영합니다.

비동기 폴링 패턴은 대부분의 통합에서 문제가 발생하는 지점입니다. Apidog의 테스트 시나리오에서 적절한 테스트는 변수 추출(Extract Variable) 단계, 중단 조건이 있는 폴링 루프, 그리고 최종 URL 검증을 포함합니다. 이러한 조합은 문제가 프로덕션에 도달하기 전에 잡아냅니다.

버튼

Apidog를 무료로 다운로드하여 통합을 시작하십시오. 신용카드 정보가 필요하지 않습니다.

자주 묻는 질문 (FAQ)

그록 이미지-투-비디오 API에 어떤 모델 이름을 사용해야 하나요?

모델 이름은 grok-imagine-video입니다. POST 요청 본문의 model 필드로 전달하십시오.

image와 reference_images 매개변수의 차이점은 무엇인가요?

image 매개변수는 출력 비디오의 첫 번째 프레임을 설정합니다. 모델은 해당 시작 이미지에서 애니메이션을 만듭니다. reference_images 배열은 프레임으로 사용되지 않고 스타일 및 내용 안내를 제공합니다. 동일한 요청에서 둘 다 결합할 수 있습니다.

비디오 생성은 얼마나 걸리나요?

생성 시간은 재생 시간과 해상도에 따라 다릅니다. 6초짜리 480p 비디오는 일반적으로 1~3분이 걸립니다. 15초짜리 720p 비디오는 4~8분이 걸릴 수 있습니다. 요청 제한을 소진하지 않으려면 5초마다 폴링하여 상태를 확인하십시오.

로컬 파일을 원본 이미지로 사용할 수 있나요?

예. 로컬 파일을 Base64 데이터 URI로 인코딩하십시오: data:image/jpeg;base64,{encoded_bytes}. 이 문자열을 image 객체 내의 url 값으로 전달하십시오.

aspect_ratio를 지정하지 않으면 어떻게 되나요?

image 매개변수를 제공하면 화면 비율은 원본 이미지의 기본 비율에 맞춰 기본 설정됩니다. 이미지 없이 텍스트-투-비디오를 생성할 경우 기본값은 16:9입니다.

10초짜리 720p 비디오는 얼마인가요?

입력 이미지 비용은 $0.002입니다. 출력 비용은 10 × $0.07 = $0.70입니다. 총계: 비디오당 약 $0.702입니다.

요청 제한은 어떻게 되나요?

API는 분당 60회, 초당 1회 요청을 허용합니다. 이는 생성 POST와 폴링 GET 요청을 모두 포함합니다.

비디오를 15초 이상으로 확장할 수 있나요?

예, POST /v1/videos/extensions 엔드포인트를 사용하여 가능합니다. 초기 클립을 최대 15초까지 생성한 다음, 추가 생성 단계를 통해 확장합니다. 각 확장도 비동기 폴링 패턴을 따릅니다.