ToAPIs
    홈ToAPIs
    이미지 생성GPT Image 2.6, Gemini, FLUX…비디오 생성Seedance, Veo, Kling, Sora…채팅 및 글쓰기GPT-5.6, Claude, DeepSeek…음성 및 음악더빙, TTS, 오디오
    신규 출시Seedance 2.5
    요금제API 문서MCP
    블로그대안
    로그인무료 시작
    전체 모델요금제API 문서MCP블로그대안
    로그인무료 시작

    언어

    Esc
    • Seedance 2.5비디오 생성
    • GPT Image 2이미지 생성
    • GPT Image 2.6이미지 생성
    • GPT Image 2.5이미지 생성
    • Veo 3.1 Fast비디오 생성
    • Kling 3.0 Turbo비디오 생성
    • Kling V4 Flash비디오 생성
    • Grok Video 1.5비디오 생성
    • Nano Banana 2이미지 생성
    • Seedream 5.5이미지 생성
    • FLUX이미지 생성
    • Sora 2비디오 생성
    • 전체 이미지 모델카테고리
    • 전체 비디오 모델카테고리
    • GPT-5.6 Sol채팅 및 코딩
    • Claude Opus 4.8채팅 및 코딩
    • Claude Opus 4.7채팅 및 코딩
    • DeepSeek V4 ProDeepSeek · 텍스트
    • Gemini Omni 1.1 FlashGoogle · 멀티모달
    1. 홈
    2. 블로그
    3. 튜토리얼
    4. Grok-Video-3 API 실습 가이드: xAI 비디오 엔진에서 먼저 확인해야 할 현재 계약
    전체 글 목록으로
    tutorial2026-11-177 분 읽기

    Grok-Video-3 API 실습 가이드: xAI 비디오 엔진에서 먼저 확인해야 할 현재 계약

    ToAPIs에서 xAI Grok Video를 호출하는 실습 가이드. 공개 카탈로그에 있는 ID는 grok-video-1.0과 grok-video-1.5이며 grok-video-3가 아닙니다. 현재 generations 계약, 모드, 폴링 경로를 정리합니다.

    ToAPIs Engineering & Evaluation Team
    Grok VideoVideo APIxAIText-to-VideoTutorial
    TL;DR - 핵심 요약
    • 공개 카탈로그 스냅샷 날짜는 2026-11-10입니다. 2026-11-17에 문서와 모델 가이드 페이지를 다시 확인해도 공개 ToAPIs 모델 ID 이름은 grok-video-3가 없습니다. 문서화된 Grok Video ID는 grok-video-1.0과 grok-video-1.5입니다.
    • Bearer API 키로 POST /v1/videos/generations에 제출하고, 작업 id를 저장한 뒤 GET /v1/videos/generations/{id}를 폴링하세요. 문서화되지 않은 /videos/tasks 경로는 사용하지 마세요.
    • grok-video-1.5는 text_to_video, first_frame_image_to_video, reference_images_to_video 세 가지 명시적 모드를 문서화합니다. video_generation_mode는 실제로 보내는 미디어와 일치해야 합니다.
    • 이미지는 공개 http(s) URL만 사용합니다. 로컬 파일은 먼저 POST /v1/uploads/images로 업로드하세요. 이 생성 API는 base64를 받지 않습니다.
    • 기획 초안의 검증되지 않은 초당 단가나 SLA 수치를 재사용하지 마세요. 샷 리스트를 예측하기 전에 계정에서 현재 요율과 채널 지원 여부를 확인하세요.

    Grok-Video-3 API 실습 가이드: xAI 비디오 엔진에서 먼저 확인해야 할 현재 계약

    대상 모델: grok-video-1.5, grok-video-1.0
    추론 엔드포인트: https://api.toapis.com/v1/videos/generations
    관련 글: OpenAI 호환 접근 · Grok Imagine 공식 채널 API · Hailuo 2.3 비디오 가이드 · Grok Video 1.5 레퍼런스


    1. 핵심 요약 및 개요 (TL;DR)

    • 카탈로그부터: Grok Video 3 실습이라도 호출은 ToAPIs가 실제로 공개한 ID에서 시작해야 합니다. 2026-11-10자 공개 프로덕션 카탈로그 스냅샷은 openai-video 엔드포인트에 grok-video-1.0과 grok-video-1.5를 나열합니다. 2026-11-17에 grok-video-3 문서와 모델 가이드 URL을 확인한 결과는 HTTP 404였습니다.
    • 계약: POST /v1/videos/generations에 비동기로 제출한 뒤 GET /v1/videos/generations/{id}를 completed 또는 failed까지 폴링합니다. 공식 예시는 https://toapis.com(중국 본토는 https://toapis.cn)입니다. 이 시리즈의 다른 가이드는 https://api.toapis.com을 사용합니다. 오리진은 하나만 골라 일관되게 쓰세요.
    • 모드: grok-video-1.5는 text_to_video, first_frame_image_to_video, reference_images_to_video를 문서화합니다. video_generation_mode를 명시해 참조 이미지 한 장이 레거시 첫 프레임 작업으로 처리되지 않게 하세요.
    • 미디어: 공개 http:// 또는 https:// URL만 보내세요. 로컬 파일은 POST /v1/uploads/images로 업로드하고 반환된 data.url을 사용하세요. base64는 보내지 마세요.
    • 버려야 할 미검증 주장: 기획 초안의 grok-video-3 ID, 99.95% SLA, 고정 $0.030–$0.038 초당 요율, 미래 오디오 출시일은 현재 ToAPIs 문서가 아닙니다. 실시간 요율과 채널 지원은 계정에서 확인하세요.

    2. 현재 Grok Video ID와 생성 모드

    model 필드에는 공개 모델 이름을 사용하세요. 공급자 고유 이름, URL 슬러그, 미공개 grok-video-3 문자열로 바꾸지 마세요.

    카탈로그 ID문서화된 작업길이(문서)해상도이미지 입력
    grok-video-1.5텍스트, 첫 프레임, 또는 1–7장 참조 이미지. video_generation_mode로 지정정수 1–15초참조 모드는 480p 또는 720p. 텍스트와 첫 프레임은 채널이 지원하면 1080p첫 프레임: image 또는 input_reference로 정확히 1장. 참조 모드: 1–7장의 reference_images
    grok-video-1.0텍스트-투-비디오와 이미지-투-비디오생성 레퍼런스: 1–15초(기본값 8). 모델 가이드 / Playground: 현재 사용 가능한 변형은 6초 상한480p, 720p선택적 image와 reference_images. 합계 최대 8장

    grok-video-1.5의 새 연동은 모드를 명시하세요.

    video_generation_mode필수 입력생략해야 할 것
    text_to_video비어 있지 않은 prompt모든 이미지 필드
    first_frame_image_to_videoimage 또는 input_reference에 첫 프레임 정확히 1장두 별칭에 서로 다른 값을 넣지 말 것. 계정 레퍼런스가 달리 말하지 않으면 참조 목록을 함께 보내지 말 것
    reference_images_to_videoprompt와 1–7장의 reference_images(문자열 또는 {"url":"..."} 객체)이 모드 없이 reference_images 한 장만 보내는 것. 레거시 단일 이미지 입력은 첫 프레임 동작으로 남습니다

    견적 성공이 생성 채널이 열려 있다는 보장은 아닙니다. 모드는 호환 채널에서 켜진 뒤에만 사용할 수 있으며, 지원되지 않는 조합은 작업 생성 전에 거부될 수 있습니다.

    Grok Video 레퍼런스의 일반적인 화면비는 16:9, 9:16, 3:2, 2:3, 1:1입니다. 사용 가능 여부는 채널에 따라 다르므로 해당 ID에서 확인한 값을 보내세요.

    빈 입력 프레임이 육각형 게이트웨이를 지나 하나의 출력 프레임이 되는 그림

    그림 1: 프롬프트(와 선택적 공개 이미지 URL)를 POST /v1/videos/generations에 제출하고, 같은 작업 id를 폴링한 뒤, status가 completed일 때만 result.data[0].url을 읽습니다.

    공식 채널 Grok Imagine의 비디오 연장 등이 필요하면 다른 ID 계열입니다. Imagine 공식 채널 가이드를 보세요. 다른 길이 체계의 두 번째 비디오 계약은 Hailuo 2.3 가이드를 참고하세요.


    3. 프로덕션 구현: cURL과 Python

    이 시리즈의 국제 예시는 https://api.toapis.com을 사용합니다. 공식 문서는 중국 본토 사용자에게 https://toapis.cn을 안내합니다. 환경마다 오리진은 하나만 유지하세요. 경로, 모델 ID, Bearer 헤더는 같습니다.

    단계 1: cURL로 grok-video-1.5 제출하기

    bash
    curl -X POST "https://api.toapis.com/v1/videos/generations" \
      -H "Authorization: Bearer $TOAPIS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "grok-video-1.5",
        "prompt": "A cinematic product shot with a slow camera push-in",
        "video_generation_mode": "text_to_video",
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "16:9"
      }'
    

    첫 프레임 작업은 같은 경로에 "video_generation_mode": "first_frame_image_to_video"와 image URL을 사용합니다. 참조 이미지 작업은 "video_generation_mode": "reference_images_to_video"와 reference_images 목록을 설정하고 resolution은 480p 또는 720p로 유지합니다.

    단계 2: Python 제출 및 폴링 도우미

    아래 예시는 문서화된 작업 상태 경로와 queued / in_progress / completed / failed 상태를 따릅니다. 배포 전에 계정 API 레퍼런스에서 id, result.data[0].url, 응답 구조를 확인하세요.

    python
    import os
    import time
    import requests
    
    API_KEY = os.environ["TOAPIS_API_KEY"]
    BASE = "https://api.toapis.com"
    ENDPOINT = f"{BASE}/v1/videos/generations"
    HEADERS = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    
    
    def dispatch_grok_video(
        prompt: str,
        *,
        model: str = "grok-video-1.5",
        mode: str = "text_to_video",
        duration: int = 8,
        resolution: str = "720p",
        aspect_ratio: str = "16:9",
        image_url: str | None = None,
        reference_images: list[str] | None = None,
    ) -> str:
        if model == "grok-video-3":
            raise ValueError("grok-video-3 is not a current public catalog ID")
        if mode == "reference_images_to_video" and resolution not in {"480p", "720p"}:
            raise ValueError("reference mode is documented as 480p or 720p")
        payload = {
            "model": model,
            "prompt": prompt,
            "duration": duration,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        }
        if model == "grok-video-1.5":
            payload["video_generation_mode"] = mode
        if mode == "text_to_video" and (image_url or reference_images):
            raise ValueError("text_to_video rejects image fields")
        if mode == "first_frame_image_to_video":
            if not image_url:
                raise ValueError("first-frame mode requires exactly one image URL")
            payload["image"] = image_url
        if mode == "reference_images_to_video":
            refs = reference_images or []
            if not (1 <= len(refs) <= 7):
                raise ValueError("reference mode requires 1-7 image URLs")
            payload["reference_images"] = refs
        res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
        res.raise_for_status()
        data = res.json()
        task_id = data.get("id") or data.get("task_id")
        if not task_id:
            raise RuntimeError(f"Unexpected submission envelope: {data}")
        return task_id
    
    
    def poll_task(task_id: str, deadline_s: int = 600) -> str:
        poll_url = f"{BASE}/v1/videos/generations/{task_id}"
        interval = 10.0
        start = time.time()
        time.sleep(5)
        while time.time() - start < deadline_s:
            poll = requests.get(poll_url, headers=HEADERS, timeout=15)
            if poll.status_code == 429:
                retry_after = poll.headers.get("Retry-After")
                time.sleep(float(retry_after) if retry_after else min(interval * 2, 120))
                continue
            poll.raise_for_status()
            data = poll.json()
            status = data.get("status")
            if status == "completed":
                return data["result"]["data"][0]["url"]
            if status == "failed":
                raise RuntimeError(f"Generation failed: {data.get('error')}")
            time.sleep(interval)
            interval = min(interval * 1.5, 30.0)
        raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
    
    
    if __name__ == "__main__":
        task_id = dispatch_grok_video(
            "A cinematic product shot with a slow camera push-in",
            mode="text_to_video",
            duration=8,
            resolution="720p",
        )
        print("Task:", task_id)
        print("Video:", poll_task(task_id))
    

    프롬프트 템플릿 버전을 작업 기록과 함께 저장해 모델·모드 변경과 문구 변경을 구분하세요. expires_at 전에 파일을 다운로드하세요. 상태 레퍼런스는 30일 보관 기간을 문서화합니다.


    4. 오류 처리 및 상태 매트릭스

    아래 표는 진단 출발점이며 ToAPIs 오류 코드와 완전히 일치한다고 보장하지 않습니다. HTTP 조회가 성공해도 작업 status를 읽어야 합니다. 요청 오류와 status: failed 이유(content_policy_rejected, insufficient_user_balance, generation_timeout 등)는 오류 레퍼런스를 보세요.

    HTTP 또는 작업 상태흔한 분류권장 조치
    400잘못된 필드, 모드/미디어 불일치, 지원되지 않는 조합정확한 카탈로그 ID, video_generation_mode가 이미지 필드와 일치하는지, 참조 모드가 480p 또는 720p인지, 이미지 값이 공개 URL인지 확인
    401API 키 누락 또는 무효ToAPIs 대시보드에서 키를 교체하고 Authorization: Bearer 헤더를 확인
    429속도 또는 동시성 제한Retry-After가 있으면 따르고, 지터와 함께 백오프하며, 안전할 때만 재시도
    5xx 또는 클라이언트 시간 초과게이트웨이 또는 업스트림 일시 문제재제출 전에 기존 작업 id를 조회
    status: queued 또는 in_progress오류가 아님기다렸다가 다시 폴링. 두 번째 작업을 만들지 말 것
    status: failed생성이 성공하지 않음error.code와 error.message(있으면 error.reason)를 읽기. 정책으로 거부된 본문을 그대로 재시도하지 말 것

    WaitTime=min⁡(MaxWait,BaseInterval×2attempt)+Uniform(0,1)\text{WaitTime} = \min(\text{MaxWait}, \text{BaseInterval} \times 2^{\text{attempt}}) + \text{Uniform}(0, 1)WaitTime=min(MaxWait,BaseInterval×2attempt)+Uniform(0,1)


    5. 요금과 FinOps ROI

    Estimated cost=successful billable jobs×current account rate for that model, duration, and resolution\text{Estimated cost} = \text{successful billable jobs} \times \text{current account rate for that model, duration, and resolution}Estimated cost=successful billable jobs×current account rate for that model, duration, and resolution

    • 기획 초안 단가를 재사용하지 마세요. grok-video-1.5 API 레퍼런스는 요금이 현재 계정과 SKU 설정을 따르며, 해당 페이지가 고정 초당 가격을 보장하지 않는다고 명시합니다. ToAPIs 요금 페이지의 공식 벤더 참고 행은 표시용이며 계정 청구와 다를 수 있습니다.
    • 견적은 채널 보장이 아닙니다. 1.5 레퍼런스는 견적 성공이 생성 채널 가용성을 의미하지 않는다고 적습니다.
    • 프롬프트 계층에서 지출을 제어하세요. 720p와 8초 전후 중간 길이로 초안을 만들고, 버전 관리된 템플릿을 유지하며, 한 번에 변수 하나만 바꾸고, 클라이언트 시간 초과 후에는 상태를 확인한 뒤에만 재제출하세요.
    • 공식 벤더 계약에는 연간 약정, 좌석 할당, 선불 하한이 붙는 경우가 많습니다. ToAPIs 과금은 보통 사용량 기준입니다. 계정의 현재 조건을 확인하세요.

    6. 자주 묻는 질문

    frontmatter의 FAQ를 보세요. 요약: grok-video-3는 현재 공개 카탈로그 ID가 아닙니다. grok-video-1.5 또는 grok-video-1.0으로 시작하고, 1.0 길이 상한은 채널별 확인 사항이며, 동기 오디오는 문서화되어 있지 않고, 항상 generations 상태 경로를 폴링하고 작업 id를 저장하세요.


    7. 액션 체크리스트

    • ToAPIs 개발자 포털에서 키를 만듭니다.
    • GET /v1/models?type=video로 키에 grok-video-1.5 또는 grok-video-1.0이 보이는지 확인합니다. 목록과 API 레퍼런스에 나중에 나타나지 않는 한 grok-video-3를 보내지 마세요.
    • video_generation_mode: "text_to_video", duration: 8, resolution: "720p"로 위 cURL을 스모크 테스트합니다.
    • 기한을 두고 GET /v1/videos/generations/{id}를 폴링하고 expires_at 전에 결과를 다운로드합니다.
    • 다음: 기존 클라이언트를 ToAPIs로 향하게 하려면 OpenAI 호환 접근 가이드, 현재 카탈로그는 Grok Video 1.5 모델 가이드. 1.0에서 6초를 넘는 길이에 의존하기 전에 Grok Video 1.0 모델 가이드를 확인하세요.

    본문에서 언급된 모델 및 API

    xAIVIDEO

    grok-video-1.0

    현재 요율:2 credits /second
    모델 가이드콘솔에서 테스트API 키 발급
    xAIVIDEO

    Grok Video 1.5

    현재 요율:3.824 credits /second
    모델 가이드콘솔에서 테스트API 키 발급

    관련 기술 블로그

    tutorial2026-11-17T10:00:00+08:006분 읽기

    OpenAI 호환 엔드포인트로 Grok Video 3 API에 접근하기

    OpenAI 호환 클라이언트를 ToAPIs로 향하게 해 현재 Grok Video 카탈로그 ID를 호출합니다. Bearer 인증과 /v1 오리진은 공유하고, 비디오 작업은 미공개 grok-video-3 경로가 아니라 POST /v1/videos/generations를 사용합니다.

    TO
    ToAPIs Engineering & Evaluation Team
    #Grok Video
    tutorial2026-11-20T10:00:00+08:009분 읽기

    Alibaba Wan 3.0 비디오 API: 차세대 비디오 생성 시작하기

    ToAPIs에서 wan3.0-video와 wan3.0-video-prime을 다루는 프로덕션 빠른 시작입니다. 하나의 All-in-One 엔드포인트, 첫·끝 프레임과 참조 미디어의 배타 규칙, 파일 또는 링크 참조, 비디오 편집 제약, 문서화된 폴링 경로를 다룹니다.

    TO
    ToAPIs Engineering & Evaluation Team
    #Wan 3.0
    tutorial2026-11-18T10:00:00+08:009분 읽기

    Kling 3.0 Omni API 심층 분석: 멀티샷 비디오 생성과 물리 일관성

    ToAPIs에서 kling-v3-omni를 다루는 실습 가이드입니다. 공식 Omni 플레이스홀더, image_list / video_list / element_list, 첫·끝 프레임, 문서화된 폴링 경로를 다루며 문서화되지 않은 shots 배열은 사용하지 않습니다.

    TO
    ToAPIs Engineering & Evaluation Team
    #Kling Omni
    ToAPIs
    홈ToAPIs
    엔터프라이즈 AI API 게이트웨이. GPT-5, Claude, Gemini 등 200개 이상의 모델을 하나의 통합 API로 이용하세요.

    인기 모델

    • Seedance 2.5 API
    • Seedance 2.0 API
    • Veo 3.1 Fast API
    • Kling 3.0 Turbo API
    더 보기접기
    • GPT Image 2 API
    • Claude Opus 4.8 API
    • Nano Banana 2 API
    • Seedance 2 Mini API
    • 전체 모델

    API 카테고리

    • AI 이미지 생성 API
    • AI 동영상 생성 API
    • 텍스트 동영상 API
    • 이미지 동영상 API
    더 보기접기
    • AI 이미지 편집 API
    • 언어 및 추론 모델 API
    • 모든 API 도구 →

    대안

    대안
    • Kie.ai 대안
    • Fal.ai 대안
    • OpenRouter 대안
    • Replicate 대안
    • Wavespeed AI 대안
    • 모든 서비스 비교 →

    추천 기술 가이드

    추천 기술 가이드
    • Seedance 2.0과 2.5 가격 비교
    • 저비용 Seedance API 가이드
    • MiniMax H3 연동 가이드
    • Seedance 2 무료 테스트 키
    • Seedance 2 API 빠른 시작
    • 모든 기술 문서 →

    개발자 및 플랫폼

    개발자 및 플랫폼
    • API 문서
    • MCP
    • 요금
    • 모델 플레이그라운드
    • LLMs.txt
    • 지원 문의
    • 모델 가이드 목록
    운영 주체:
    鯨樞智能科技有限公司
    JINGSHU INTELLIGENT LIMITED
    등록 주소:
    ROOM 5042, 5/F, YAU LEE CENTRE, NO.45, HOI YUEN ROAD, KWUN TONG, KOWLOON, HONG KONG
    개인정보처리방침이용약관이용 정책데이터 삭제 정책데이터 보존 정책하위 처리자 및 데이터 리전결제 및 환불쿠키 정책사이트맵소개

    © 2026 ToAPIs. All rights reserved.