비디오 생성을 위해 웹훅과 폴링은 어떻게 사용하나요?

비디오 생성에서는 모든 비동기 작업이 조회 가능한 task ID를 반환하므로 폴링을 기본 방식으로 사용하세요. 선택한 비디오 엔드포인트가 callback URL을 지원할 때만 웹훅을 추가하고, 누락되었거나 provider별로 다르게 전달되는 콜백에 대해서는 폴링을 기준 정보로 유지하세요.

비디오 task 생성

다음 요청은 최소한의 비디오 task를 생성하고 반환된 ID를 저장합니다. 선택한 model 페이지에 해당 필드가 문서화되어 있을 때만 duration, resolution 또는 callback 필드를 추가하세요.

curl https://api.cometapi.com/v1/videos \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -F "model=doubao-seedance-2-0" \
  -F "prompt=A cinematic shot of a paper airplane crossing a desk"

응답에는 task ID와 status가 포함됩니다:

{
  "id": "task_example",
  "task_id": "task_example",
  "object": "video",
  "model": "doubao-seedance-2-0",
  "status": "queued",
  "progress": 0,
  "created_at": 1779872000
}

상태 폴링

다음 요청은 비디오 task 상태를 확인합니다:

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

응답은 task가 진행됨에 따라 변경됩니다. 완료된 응답에는 model adapter에 결과 URL이 있을 때 video_url이 포함될 수 있습니다. 그렇지 않으면 model별 결과 필드 또는 해당 model이 프록시 다운로드를 지원할 때 /v1/videos/{id}/content 콘텐츠 경로를 사용하세요.

{
  "id": "task_example",
  "object": "video",
  "model": "doubao-seedance-2-0",
  "status": "completed",
  "progress": 100,
  "completed_at": 1779872300,
  "video_url": "<generated-video-url>"
}

웹훅 수신

CometAPI는 모든 비디오 model에 대해 하나의 공통 callback payload를 정의하지 않습니다. 콜백은 provider별 패스스루 이벤트로 취급하고, 원본 body를 저장한 다음, 폴링으로 최종 상태를 대조하세요. 다음 Express 핸들러는 비디오 콜백을 수신하고 이벤트를 저장합니다:

import express from "express";

const app = express();
app.use(express.json({ limit: "2mb" }));

app.post("/cometapi/video-webhook", async (request, response) => {
  const event = request.body;

  console.log("Task ID:", event.task_id || event.id);
  console.log("Status:", event.status);

  response.status(200).json({ received: true });
});

app.listen(3000);

콜백 payload에는 일반적으로 task 식별 정보와 status 필드가 포함되지만, 정확한 중첩 구조는 선택한 model 또는 provider에 따라 달라집니다:

{
  "task_id": "task_example",
  "status": "completed",
  "progress": 100,
  "result": {
    "video_url": "https://example.com/result.mp4"
  }
}

일반적인 오류

오류	해결 방법
콜백 유실	앱이 최종 상태를 저장할 때까지 task ID로 폴링하세요.
중복 콜백	task ID 기준으로 콜백 처리가 멱등적이도록 만드세요.
콜백 거부	먼저 `2xx` 응답을 빠르게 반환한 뒤, 백그라운드에서 작업을 처리하세요.
provider별 payload 불일치	원본 콜백 payload를 저장하고 앱에서 정규화하세요.
`video_url` 누락	`video_url`은 선택 사항으로 취급하고, 가능할 때는 폴링과 model별 결과 필드 또는 `/v1/videos/{id}/content`를 함께 사용하세요.

Documentation Index

​비디오 task 생성

​상태 폴링

​웹훅 수신

​일반적인 오류

​관련 링크

비디오 task 생성

상태 폴링

웹훅 수신

일반적인 오류

관련 링크