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

# 비디오 다운로드

## 소개

비디오 다운로드 API는 완료된 비디오 파일 데이터를 가져오는 데 사용됩니다. **참고: 이 API는 Sora 2 모델에서만 지원됩니다**. 다른 모델(Veo, Ali Wanxiang, Doubao Seedance)은 작업이 성공한 후 조회 작업 API 응답에 비디오 URL이 직접 포함되므로 별도의 다운로드 단계가 필요하지 않습니다.

## 인증

<ParamField header="Authorization" type="string" required>
  Bearer Token, 예: `Bearer sk-xxxxxxxxxx`
</ParamField>

## 쿼리 매개변수

<ParamField query="id" type="string" required>
  비디오 ID, 조회 작업 API에서 반환된 `task_id`
</ParamField>

## 사용 예제

```bash theme={null}
curl -X GET "https://api.gravitex.ai/v1/video/generations/download?id=video_69095b4ce0048190893a01510c0c98b0" \
  -H "Authorization: Bearer sk-xxxxxxxxxx"
```

## 응답 예제

```json theme={null}
{
  "success": true,
  "generation_id": "video_69095b4ce0048190893a01510c0c98b0",
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "format": "mp4",
  "size": 15728640,
  "base64": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZQAAB...",
  "data_url": "data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZQAAB..."
}
```

## 응답 필드 설명

| 필드              | 타입      | 설명                                                  |
| --------------- | ------- | --------------------------------------------------- |
| `success`       | boolean | 성공 여부                                               |
| `generation_id` | string  | 생성 ID (videoId와 동일)                                 |
| `task_id`       | string  | 작업 ID                                               |
| `format`        | string  | 비디오 형식 (`"mp4"` 고정)                                 |
| `size`          | number  | 비디오 파일 크기(바이트)                                      |
| `base64`        | string  | Base64로 인코딩된 비디오 데이터                                |
| `data_url`      | string  | Data URL 형식의 비디오 데이터, 프론트엔드 `<video>` 태그에서 바로 사용 가능 |

## 사용 안내

### data\_url을 사용한 프론트엔드 사용

`data_url` 필드는 HTML `<video>` 태그에서 바로 사용할 수 있습니다:

```html theme={null}
<video src="data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZQAAB..." controls></video>
```

### 파일 다운로드 및 저장

`base64` 필드를 사용하여 비디오를 파일로 저장합니다:

#### JavaScript 예제

```javascript theme={null}
// Get base64 data from response
const response = await fetch('https://api.gravitex.ai/v1/video/generations/download?id=video_xxx', {
  headers: {
    'Authorization': 'Bearer sk-xxxxxxxxxx'
  }
});
const data = await response.json();

// Convert base64 to Blob
const binaryString = atob(data.base64);
const bytes = new Uint8Array(binaryString.length);
for (let i = 0; i < binaryString.length; i++) {
  bytes[i] = binaryString.charCodeAt(i);
}
const blob = new Blob([bytes], { type: 'video/mp4' });

// Create download link
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'video.mp4';
a.click();
URL.revokeObjectURL(url);
```

#### Python 예제

```python theme={null}
import requests
import base64

def download_video(video_id, api_key):
    """Download video and save as file"""
    url = f"https://api.gravitex.ai/v1/video/generations/download?id={video_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    response = requests.get(url, headers=headers)
    data = response.json()
    
    if data.get("success"):
        # Decode base64 data
        video_data = base64.b64decode(data["base64"])
        
        # Save as file
        with open("video.mp4", "wb") as f:
            f.write(video_data)
        
        print(f"✅ Video saved: video.mp4 (size: {data['size']} bytes)")
        return True
    else:
        print("❌ Download failed")
        return False
```

## 전체 워크플로 예제 (Sora 2)

1. **비디오 생성 작업 제출**

   ```bash theme={null}
   curl -X POST "https://api.gravitex.ai/v1/video/generations" \
     -H "Authorization: Bearer sk-xxxxxxxxxx" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "sora-2",
       "prompt": "A cute little cat playing in the garden",
       "seconds": "4",
       "size": "720x1280"
     }'
   ```

   응답:

   ```json theme={null}
   {
     "task_id": "video_69095b4ce0048190893a01510c0c98b0",
     "status": "submitted",
     "format": "mp4"
   }
   ```

2. **작업 상태 조회** (성공할 때까지 폴링)

   ```bash theme={null}
   curl -X GET "https://api.gravitex.ai/v1/video/generations/video_69095b4ce0048190893a01510c0c98b0" \
     -H "Authorization: Bearer sk-xxxxxxxxxx"
   ```

   `status`가 `succeeded`이면 다음 단계로 진행합니다.

3. **비디오 파일 다운로드**
   ```bash theme={null}
   curl -X GET "https://api.gravitex.ai/v1/video/generations/download?id=video_69095b4ce0048190893a01510c0c98b0" \
     -H "Authorization: Bearer sk-xxxxxxxxxx"
   ```

## 관련 API

<Columns cols={2}>
  <Card title="비디오 작업 제출" icon="upload" href="/ko/api-reference/endpoint/submit-video-task">
    비디오 생성 작업 제출
  </Card>

  <Card title="비디오 작업 조회" icon="search" href="/ko/api-reference/endpoint/query-video-task">
    비디오 생성 작업 상태 및 결과 조회
  </Card>
</Columns>