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

# 비디오 생성 API

> Seedance, HappyHorse, Sora 2, Veo 3, Wan, xAI, Vidu, Omni, Kling, Runway 워크플로에 맞는 CometAPI 비디오 라우트를 선택하세요.

작업 유형에 맞는 provider 워크플로를 선택해 CometAPI 비디오 모델 문서를 사용하세요. 대부분의 비디오 엔드포인트는 비동기 작업을 생성하므로 task ID를 저장하고 polling으로 결과를 가져오세요. 콜백은 모델별 페이지에 콜백 지원이 문서화된 경우에만 추가하세요.

## 비디오 API 선택하기

<CardGroup cols={2}>
  <Card title="Seedance 비디오 생성" icon="sparkles" href="/api/video/seedance/create">
    Seedance 비디오 작업을 생성합니다.
  </Card>

  <Card title="HappyHorse 비디오 생성" icon="sparkles" href="/api/video/happyhorse/create">
    HappyHorse 텍스트-투-비디오 작업을 생성합니다.
  </Card>

  <Card title="Sora 2 비디오 생성" icon="film" href="/api/video/sora-2/create">
    Sora 2 비디오 작업을 생성합니다.
  </Card>

  <Card title="Sora 2 비디오 조회" icon="refresh" href="/api/video/sora-2/retrieve">
    Sora 비디오 작업을 조회합니다.
  </Card>

  <Card title="Veo 3 비디오 생성" icon="film" href="/api/video/veo3/create">
    Veo 비디오 작업을 생성합니다.
  </Card>

  <Card title="Wan 비디오 생성" icon="sparkles" href="/api/video/wan/create">
    Wan 텍스트-투-비디오 작업을 생성합니다.
  </Card>

  <Card title="xAI 비디오 생성" icon="film" href="/api/video/xai/video-generation">
    xAI 비디오 작업을 생성합니다.
  </Card>

  <Card title="Vidu 비디오 생성" icon="sparkles" href="/api/video/vidu/create">
    Vidu 텍스트-투-비디오 작업을 생성합니다.
  </Card>

  <Card title="Omni 비디오 생성 (베타)" icon="sparkles" href="/api/video/omni/create">
    베타 Omni 비디오 작업을 생성합니다.
  </Card>

  <Card title="Kling 텍스트-투-비디오 작업 생성" icon="film" href="/api/video/kling/text-to-video">
    텍스트 프롬프트(Prompt)로 Kling 비디오를 생성합니다.
  </Card>

  <Card title="Runway 이미지-투-비디오 작업 생성" icon="film" href="/api/video/runway/official-format/runway-images-raw-video">
    이미지로 Runway 비디오를 생성합니다.
  </Card>
</CardGroup>

## 비디오 작업 생성 및 폴링

[Models 페이지](/ko/overview/models) 또는 [model directory](https://www.cometapi.com/models/)에서 비디오를 지원하는 model ID를 사용하세요. 아래 예제는 `POST /v1/videos`로 비디오 작업을 생성한 다음, 작업이 종료 상태에 도달할 때까지 반환된 작업 ID를 폴링합니다.

<Note>
  이 예제들은 `your-video-model-id` 플레이스홀더를 사용합니다. 요청을 실행하기 전에 [Models 페이지](/ko/overview/models) 또는 [model directory](https://www.cometapi.com/models/)에서 사용 가능한 비디오 model ID로 교체하세요.
</Note>

<Tip>
  API 플레이그라운드와 엔드포인트 스키마를 사용하려면 [Create a Seedance video](/api/video/seedance/create)와 [Retrieve a Seedance video](/api/video/seedance/query)를 여세요.
</Tip>

<CodeGroup>
  ```python Python theme={null}
  import os
  import time
  import requests

  headers = {"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]}

  create_response = requests.post(
      "https://api.cometapi.com/v1/videos",
      headers=headers,
      data={
          "model": "your-video-model-id",
          "prompt": "A calm camera move across a desk with a paper airplane",
      },
      timeout=30,
  )
  create_response.raise_for_status()
  task = create_response.json()
  task_id = task["id"]

  terminal_statuses = {"completed", "failed", "error"}

  while True:
      poll_response = requests.get(
          f"https://api.cometapi.com/v1/videos/{task_id}",
          headers=headers,
          timeout=30,
      )
      poll_response.raise_for_status()
      result = poll_response.json()
      print(result["status"], result.get("progress"))

      if result["status"] in terminal_statuses:
          print(result.get("video_url"))
          break

      time.sleep(10)
  ```

  ```javascript Node.js theme={null}
  const form = new FormData();
  form.append("model", "your-video-model-id");
  form.append("prompt", "A calm camera move across a desk with a paper airplane");

  const createResponse = await fetch("https://api.cometapi.com/v1/videos", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
    },
    body: form,
  });

  if (!createResponse.ok) {
    throw new Error(await createResponse.text());
  }

  const task = await createResponse.json();
  const terminalStatuses = new Set(["completed", "failed", "error"]);

  while (true) {
    const pollResponse = await fetch(
      `https://api.cometapi.com/v1/videos/${task.id}`,
      {
        headers: {
          Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
        },
      },
    );

    if (!pollResponse.ok) {
      throw new Error(await pollResponse.text());
    }

    const result = await pollResponse.json();
    console.log(result.status, result.progress);

    if (terminalStatuses.has(result.status)) {
      console.log(result.video_url);
      break;
    }

    await new Promise((resolve) => setTimeout(resolve, 10_000));
  }
  ```

  ```bash cURL theme={null}
  curl https://api.cometapi.com/v1/videos \
    -H "Authorization: Bearer $COMETAPI_KEY" \
    -F "model=your-video-model-id" \
    -F "prompt=A calm camera move across a desk with a paper airplane"

  curl https://api.cometapi.com/v1/videos/task_example \
    -H "Authorization: Bearer $COMETAPI_KEY"
  ```
</CodeGroup>

## 응답 예시

성공적인 생성 응답은 다음과 같을 수 있습니다. 폴링하기 전에 작업 ID를 저장하세요:

```json theme={null}
{
  "id": "task_example",
  "task_id": "task_example",
  "object": "video",
  "model": "your-video-model-id",
  "status": "queued",
  "progress": 0,
  "created_at": 1779872000
}
```

성공적인 폴링 응답은 다음과 같을 수 있습니다. 완료된 응답에는 `video_url`이 포함될 수 있으며, 일부 provider 형식은 해당 라우트가 문서화되어 있을 때 모델별 결과 필드나 비디오 콘텐츠 라우트를 사용합니다:

```json theme={null}
{
  "id": "task_example",
  "object": "video",
  "model": "your-video-model-id",
  "status": "completed",
  "progress": 100,
  "completed_at": 1779872300,
  "video_url": "https://example.com/generated-video.mp4"
}
```

## 예시 model 레코드

<Info>
  이 예시 model 카탈로그 응답은 `/api/models` 엔벌로프와 하나의 비디오 model 레코드 형태를 보여줍니다. 전체 model 목록은 아닙니다.
</Info>

```bash cURL theme={null}
curl https://api.cometapi.com/api/models
```

```json theme={null}
{
  "success": true,
  "page": 1,
  "page_size": 20,
  "total": 302,
  "data": [
    {
      "created": 1767529753,
      "id": "your-video-model-id",
      "code": "your-video-model-id",
      "provider": "ExampleProvider",
      "provider_code": "example",
      "name": "Example video model",
      "model_type": "video",
      "features": [
        "text-to-video"
      ],
      "endpoints": "{\n  \"seedance\": {\n    \"path\": \"/v1/videos\",\n    \"method\": \"POST\"\n  }\n}",
      "pricing": {
        "currency": "USD / M Tokens",
        "input": null,
        "output": null,
        "per_request": null,
        "per_second": 0.024
      }
    }
  ]
}
```

## 일반적인 오류

<AccordionGroup>
  <Accordion title="작업 ID 누락">
    작업 핸들러에서 반환하기 전에 create 응답의 ID를 저장하세요.
  </Accordion>

  <Accordion title="너무 빠른 폴링">
    상태 확인 사이에 지연과 백오프를 추가하세요.
  </Accordion>

  <Accordion title="지원되지 않는 duration 또는 size">
    선택한 비디오 endpoint에 대해 문서화된 duration 및 resolution 필드를 사용하세요.
  </Accordion>

  <Accordion title="video_url 누락">
    `video_url`을 선택 사항으로 처리하고, 가능하면 model별 결과 필드 또는 content route로 대체하세요.
  </Accordion>

  <Accordion title="콜백이 수신되지 않음">
    폴링을 신뢰 가능한 기준으로 사용하고, callback URL이 POST 요청을 수락하는지 확인하세요.
  </Accordion>
</AccordionGroup>

## 오류 코드 및 재시도 전략

<AccordionGroup>
  <Accordion title="400">
    프롬프트(Prompt), 파일, duration 또는 size 필드가 수정될 때까지 재시도하지 마세요.
  </Accordion>

  <Accordion title="401">
    API 키가 존재하고 유효해질 때까지 재시도하지 마세요.
  </Accordion>

  <Accordion title="404">
    재시도하기 전에 작업 ID, base URL, path, model ID를 확인하세요.
  </Accordion>

  <Accordion title="413">
    재시도하기 전에 업로드 크기를 줄이세요.
  </Accordion>

  <Accordion title="429">
    지수 백오프로 재시도하고 create 또는 폴링 동시성을 줄이세요.
  </Accordion>

  <Accordion title="500 or 503">
    백오프와 함께 작업 생성을 재시도하세요. 작업이 종료 오류 상태에 도달하지 않는 한 기존 작업의 폴링은 계속하세요.
  </Accordion>
</AccordionGroup>

<Tip>
  구현 패턴은 [오류 코드 및 재시도 전략](/ko/guides/error-codes-and-retry-strategy), [속도 제한 및 동시성](/ko/guides/rate-limits-and-concurrency), [비디오 생성을 위한 웹훅 및 폴링](/ko/guides/webhook-and-polling-for-video-generation)을 참고하세요.
</Tip>

## 가격 및 model 디렉터리

<CardGroup cols={3}>
  <Card title="Models 페이지" icon="list" href="/overview/models">
    문서에서 CometAPI가 model ID를 어떻게 노출하는지 알아보세요.
  </Card>

  <Card title="Model 디렉터리" icon="puzzle-piece" href="https://www.cometapi.com/models/">
    사용 가능한 model과 기능을 살펴보세요.
  </Card>

  <Card title="가격" icon="tag" href="https://www.cometapi.com/pricing/">
    model을 호출하기 전에 가격을 확인하세요.
  </Card>
</CardGroup>