Grok Imagine 비디오 API 초보자 튜토리얼

Grok 비디오 API는 개발자가 텍스트 프롬프트를 기반으로 비디오를 생성할 수 있도록 하며, 지원되는 워크플로우의 경우 시작 이미지나 다른 참조를 사용할 수도 있습니다. 동기식 텍스트 응답과 달리 비디오 생성은 비동기식입니다. 첫 번째 요청은 작업 ID를 반환하며, 애플리케이션은 결과가 준비될 때까지 폴링해야 합니다.

본 튜토리얼은 아키텍처를 설명하고 최소한의 Python 예제를 제공합니다. 코드를 작성하기 전에 시각적 품질을 평가하려면 Elser AI의 Grok Imagine 워크스페이스에서 프롬프트를 테스트한 다음, 성공적인 샷 사양을 API로 마이그레이션할 수 있습니다.

무엇이 필요하신가요

• xAI 개발자 계정 하나;
• 안전하게 저장된 API 키;
• Python 3.10 이상 버전;
• requests 패키지;
• 비디오 파일의 영구 저장 완료;
• 예산 및 재시도 전략.

API 키를 소스 코드에 하드코딩하거나 브라우저 측 JavaScript에서 노출하지 마십시오.

API 워크플로우 작동 방식

1. /v1/videos/generations에 생성 요청을 보냅니다.
2. request_id를 수신합니다.
3. /v1/videos/{request_id}를 폴링합니다.
4. 상태가 done이 되거나 터미널 오류가 발생하면 중지합니다.
5. 생성된 URL은 임시이므로 반환된 비디오를 즉시 다운로드하시기 바랍니다.
6. 메타데이터, 프롬프트, 모델, 설정 및 비용을 저장하여 감사 및 재현 가능성을 확보합니다.

최소 텍스트-투-비디오 예제

import os
import time
from pathlib import Path

import requests


API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "grok-imagine-video-1.5",
    "prompt": (
        반사 표면 위에 열려 있는 무광 검정색 제품 상자.
        부드러운 산호색 조명이 카메라가 작동할 때 제품을 비춘다
        "천천히 줌인. 고급 스튜디오 조명, 실제 다이내믹, 텍스트 없음."
    ),
    "duration": 6,
    "resolution": "720p",
}

create = requests.post(
    f"{BASE_URL}/videos/generations"
    headers=HEADERS,
    json=부하,
    timeout=60,
)
create.raise_for_status()
request_id = create.json()["request_id"]

deadline = time.time() + 15 * 60
while time.time() < deadline:
    status_response = requests.get(
        f"{BASE_URL}/videos/{request_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=60，
    )
    status_response.raise_for_status()
    result = status_response.json()

    만약 결과가["상태"] == "완료됨":
        video_url = 결과["동영상"]["url"]
        video_response = requests.get(video_url, timeout=180)
        video_response.raise_for_status()
        Path("output.mp4").write_bytes(video_response.content)
        print("저장 완료 output.mp4")
        중단

    만약 결과가["상태"] {"expired", "failed", "cancelled"} 중에서:
        raise RuntimeError(f"생성 종료, 상태：{result['status']}")

    time.sleep(5)
그 외:
    타임아웃 오류 발생 ("비디오 생성이 마감 시간 내에 완료되지 않음")

배포 전에 xAI의 현재 API 아키텍처를 확인하세요. 모델 이름, 지원되는 매개변수 및 응답 상태가 변경될 수 있습니다.

이미지에서 동영상으로 변환

xAI의 문서는 공개 이미지 URL 또는 base64 데이터 URI를 사용한 이미지 중심 생성을 지원합니다. 개념적으로 요청은 이미지 객체를 추가합니다:

# 번역할 내용이 없습니다.

payload = { "model": "grok-imagine-video-1.5", "prompt": ( "주체, 의상, 배경을 유지하세요." 주체가 창문 쪽으로 몸을 돌리면서 카메라가 천천히 줌인된다. ), "图片": {"url": "https://example.com/source-image.png"}, "duration": 6, "resolution": "720p", }

입력이 비공개인 경우, 단기 유효한 서명 URL을 사용하세요. API 요구 사항을 충족시키기 위해 고객의 미디어 콘텐츠를 공개적으로 노출하지 마십시오.

## 프로덕션 환경 오류 처리

프로덕션 환경 클라이언트는 다음을 처리해야 합니다:

- 인증 실패;
- 검증 오류;
- 심사 거절;
- 속도 제한;
- 네트워크 시간 초과;
- 만료된 직위 또는 결과 링크；
- 중복 제출；
- 부분 저장 장애;
- 계정 예산이 소진되었습니다.

재시도 가능한 오류의 경우, 지터가 포함된 지수 백오프 전략을 사용하세요. 검증 또는 심사 실패 시 무한 재시도하지 마세요. 멱등성 키를 추가하거나 자체 작업 기록을 유지하여 네트워크 재시도로 인한 예상치 못한 중복 동영상이 발생하지 않도록 하세요.

## 비용 관리

xAI는 생성된 초 수에 따라 비디오 가격을 책정하며, 요금은 모델과 해상도에 따라 다릅니다. 미디어 입력에도 비용이 발생할 수 있습니다. 각 작업의 모델, 해상션, 시간 및 반환된 사용 데이터를 저장합니다.

유용한 보안 조치에는 다음이 포함됩니다:

- 각 요청의 최대 시간;
- 각 사용자의 일일 지출 상한;
- 저해상도 초안 모드;
- 고해상도 재렌더링 전에 승인을 받아야 합니다.
- 자동 재시도 횟수 제한;
- 이상 생성량 경보;
- 각 승인된 세그먼트 비용 보고서.

## 큐와 동시성 설계

비디오 작업은 대기열에 들어가야 합니다. 작업 노드가 요청을 제출하고, 책임감 있게 폴링하며, 완료된 파일을 영구 객체 스토리지로 전송합니다. 애플리케이션 데이터베이스는 다음을 추적해야 합니다:

- 내부 직위 ID;
- xAI 요청 ID;
- 사용자 및 프로젝트;
- 프롬프트 및 입력 참조;
- 상태 및 진행 상황;
- 타임스탬프;
- 모델 및 설정；
- 출력 저장소 URL;
- 비용 및 심사 결과.

현재 계정 수준의 속도 제한을 준수합니다. 과도한 병렬 작업으로 인해 속도 제한이나 비용 통제가 불가능해지면 아무런 이점이 없습니다.

## 보안 및 개인정보 보호

사용자가 업로드한 이미지에 대한 권한 및 식별 가능한 인물의 허가를 확인합니다. 시스템이 명백히 비자발적 친밀 이미지, 사기성 사칭, 착취 또는 불법 콘텐츠를 생성하려는 시도를 거부하도록 합니다. 서비스에 필요한 미디어와 로그만 보관하고 명확한 삭제 정책을 공개합니다.

제공자의 워터마크나 출처 표시를 제거할 수 없습니다. 전파력이 높거나 정치, 의료, 금융, 신원 민감 콘텐츠의 경우 수동 검토를 포함해야 합니다.

## API 통합 전에 코드 없는 평가 수행

크리에이티브 사양이 검증된 후에는 API 프로젝트를 더 쉽게 구현할 수 있습니다. [Elser AI의 Grok Imagine Video](https://www.elser.ai/ko/m/grok)를 사용하여 프롬프트, 참조 이미지의 적합성, 화면 비율 및 촬영 승인 기준을 테스트하세요. 팀이 사용 가능한 촬영을 안정적으로 설명할 수 있게 되면 반복적인 부분을 자동화할 수 있습니다.

## 시작 체크리스트

- API 키는 키 관리자에 저장됩니다.
- 현재 모델 및 파라미터는 xAI 문서에 따라 검증되었습니다.
- 대기열, 시간 초과, 재시도 및 멱등성 로직이 테스트되었습니다.
- 임시 URL에서 전송된 출력입니다.
- 각 사용자 및 전역 소비 제한이 활성화되었습니다.
- 심사 실패 처리, 맹목적인 재시도 하지 않음.
- 출처 권리 및 동의가 확인되었습니다.
- 로그에서 민감한 미디어와 자격 증명을 제외합니다.
- 워터마크 및 AI 공개 규칙이 문서화되어 있습니다.