> ## 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는 작업 ID로 비디오 생성 작업의 상태와 결과를 조회하는 데 사용됩니다. 작업을 제출한 후 작업이 완료되거나 실패할 때까지 이 API를 주기적으로 폴링하여 상태를 확인해야 합니다.

**중요 안내**: 작업 상태가 `succeeded` 또는 `failed`가 될 때까지 3\~5초 간격으로 폴링하는 것을 권장합니다.

## 인증

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

## 경로 매개변수

<ParamField path="task_id" type="string" required>
  작업 제출 API에서 반환된 비디오 생성 작업 ID
</ParamField>

## 응답 설명

### 작업 상태

| 상태            | 설명                   | 권장 조치                  |
| ------------- | -------------------- | ---------------------- |
| `queued`      | 작업이 대기열에 있으며 처리 대기 중 | 계속 폴링                  |
| `in_progress` | 작업 처리 중              | 계속 폴링                  |
| `succeeded`   | 작업이 성공적으로 완료됨        | 비디오 다운로드 또는 비디오 URL 확인 |
| `failed`      | 작업 실패                | 오류 원인 확인               |

### 응답 예제 (대기 중)

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

### 응답 예제 (처리 중)

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

### 응답 예제 (완료)

```json theme={null}
{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "succeeded",
  "format": "mp4",
  "url": "https://gravitex-ads.oss-cn-guangzhou.aliyuncs.com/2025/11/18/abc123/video.mp4"
}
```

**참고**: Veo와 Ali Wanxiang의 경우 작업이 성공하면 응답에 비디오 URL이 직접 포함됩니다. Sora 2는 비디오를 가져오기 위해 다운로드 API를 사용해야 합니다.

### 응답 예제 (실패)

```json theme={null}
{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "failed",
  "format": "mp4",
  "error": {
    "code": 400,
    "message": "Prompt contains inappropriate content"
  }
}
```

## 사용 예제

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

## 폴링 예제

### Python 예제

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

def poll_task_status(task_id, api_key, max_wait_time=300):
    """Poll task status until completion"""
    url = f"https://api.gravitex.ai/v1/video/generations/{task_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    start_time = time.time()
    while True:
        response = requests.get(url, headers=headers)
        data = response.json()
        status = data.get("status")
        
        print(f"Current status: {status}")
        
        if status == "succeeded":
            video_url = data.get("url")
            print(f"✅ Task completed! Video URL: {video_url}")
            return video_url
        elif status == "failed":
            error_msg = data.get("error", {}).get("message", "Unknown error")
            print(f"❌ Task failed: {error_msg}")
            return None
        
        # Check timeout
        if time.time() - start_time > max_wait_time:
            print("⏰ Timeout")
            return None
        
        # Wait 5 seconds before querying again
        time.sleep(5)
```

### JavaScript 예제

```javascript theme={null}
async function pollTaskStatus(taskId, apiKey, maxWaitTime = 300000) {
  const url = `https://api.gravitex.ai/v1/video/generations/${taskId}`;
  const headers = { 'Authorization': `Bearer ${apiKey}` };
  
  const startTime = Date.now();
  
  while (true) {
    const response = await fetch(url, { headers });
    const data = await response.json();
    const status = data.status;
    
    console.log(`Current status: ${status}`);
    
    if (status === 'succeeded') {
      const videoUrl = data.url;
      console.log(`✅ Task completed! Video URL: ${videoUrl}`);
      return videoUrl;
    } else if (status === 'failed') {
      const errorMsg = data.error?.message || 'Unknown error';
      console.error(`❌ Task failed: ${errorMsg}`);
      throw new Error(errorMsg);
    }
    
    // Check timeout
    if (Date.now() - startTime > maxWaitTime) {
      throw new Error('Timeout');
    }
    
    // Wait 5 seconds before querying again
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}
```

## 관련 API

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

  <Card title="비디오 다운로드" icon="download" href="/ko/api-reference/endpoint/download-video">
    완료된 비디오 파일 다운로드 (Sora 2 전용)
  </Card>
</Columns>