AI 동영상 생성 API: TypeScript로 텍스트를 영상으로 만들기

AI 동영상 생성 API는 비동기 실행을 통해 프롬프트를 동영상으로 바꿉니다. Video Generator를 시작하고, 반환된 실행 ID로 상태를 조회한 뒤, 완료된 실행의 에셋에서 동영상 URL을 읽으면 됩니다. Pipe2 TypeScript SDK가 이러한 공개 작업을 직접 제공하므로 텍스트-투-비디오 통합을 간결하게 구성할 수 있습니다.

TypeScript SDK로 텍스트-투-비디오 실행하기

@pipe2-ai/sdk를 설치하고 Pipe2 토큰을 PIPE2_TOKEN에 저장한 다음 이 모듈을 Node로 실행합니다. 예제는 생성기가 명확한 한 장면을 만들 수 있도록 관찰 가능한 동작 하나와 짧은 시간 흐름을 사용합니다.

import { createClient } from '@pipe2-ai/sdk';

const input = {
  prompt: '[0-3s] A paper airplane circles above a classroom. [3-6s] It lands beside a notebook. Gentle room ambience, no music.',
};
const client = createClient(process.env.PIPE2_TOKEN);
const { run_pipeline } = await client.RunPipeline({
  pipeline_slug: 'video-generator',
  input,
});

while (true) {
  const { pipeline_runs_by_pk: run } = await client.GetPipelineRun({
    id: run_pipeline.run_id,
  });
  if (run?.status === 'completed') {
    console.log(run.assets?.[0]?.url);
    break;
  }
  if (run?.status === 'failed') throw new Error(run.error_message ?? 'Video generation failed');
  await new Promise((resolve) => setTimeout(resolve, 3000));
}

인증과 상태 조회를 제외한 동일한 파이프라인 요청은 다음과 같습니다.

{
  "pipeline_slug": "video-generator",
  "input": {
    "prompt": "[0-3s] A paper airplane circles above a classroom. [3-6s] It lands beside a notebook. Gentle room ambience, no music."
  }
}

TypeScript SDK 문서에서는 설치, 인증, 파이프라인 실행, 상태 조회, 구독, 업로드, 크레딧 작업을 설명합니다.

실행, 폴링, 에셋 흐름 이해하기

RunPipeline은 파이프라인 slug와 JSON 입력 객체를 받습니다. 동영상 생성이 끝날 때까지 요청을 열어 두지 않고 새 실행의 식별자를 반환합니다. GetPipelineRun에서 사용하는 run_pipeline.run_id를 보관해야 합니다.

각 조회는 현재 실행 레코드를 반환합니다. 상태가 completed인 실행에는 생성된 에셋이 포함될 수 있으며, 예제는 첫 번째 에셋의 URL을 출력합니다. failed 실행에는 통합 서비스가 표시하거나 기록해야 할 오류 메시지가 있습니다. 운영 코드에서는 전체 제한 시간도 설정하고, 실행이 존재하지 않는 경우 무한히 조회하지 말고 오류로 처리해야 합니다.

작은 스크립트는 몇 초 간격의 폴링으로 충분합니다. 서비스가 실시간 업데이트를 받아야 한다면 SDK의 WatchPipelineRun을 사용해 동일한 실행 상태를 비동기 이터러블로 읽을 수 있습니다.

가장 단순한 유효 입력으로 시작하기

요청에는 prompt만 있습니다. 텍스트-투-비디오에 필요한 최소한의 실용 입력이며 모델 선택은 Auto로 둡니다. Video Generator는 시작 또는 종료 프레임과 선택적인 이미지, 동영상, 오디오 참조 자료도 사용할 수 있습니다. 지원되는 길이, 해상도, 화면비, 참조 자료 한도는 호환되는 모델 경로에 따라 달라집니다.

제품 요구사항에 필요한 설정만 추가하세요. 배포 대상에 맞는 화면비, 피사체 정체성을 위한 참조 이미지, 더 긴 클립을 위한 다른 호환 경로가 필요할 수 있습니다. 비용이 더 들거나 미디어가 많은 요청을 보내기 전에는 같은 pipeline_slug와 input으로 EstimatePipelineCost를 호출할 수 있습니다.

한 개의 생성 장면에 맞는 프롬프트 작성하기

API를 사용하더라도 정확한 장면 설명은 필요합니다. 눈에 보이는 동작, 카메라 움직임, 환경, 타이밍, 소리를 적고, 지정 시간 안에 물리적으로 완성될 수 있는 동작으로 제한합니다.

예제는 두 시간 구간을 사용하지만 하나의 연속된 사건을 설명합니다. 종이비행기가 선회한 뒤 공책 옆에 착륙합니다. 장소 전환, 여러 인물, 여러 편집 컷은 요구하지 않습니다. 따라서 움직임의 연속성, 물체 형태, 착륙 순간, 오디오를 더 쉽게 검토할 수 있습니다.

규모가 큰 제작에서는 각 장면을 따로 생성하고 승인한 뒤 조립하세요. AI 동영상 제작 가이드는 이 API 호출 이후의 기획, 검토, 조립, 자막, 마무리 작업을 다룹니다.

인증과 실패를 명시적으로 처리하기

Pipe2 토큰으로 클라이언트를 만들고 토큰은 서버나 안전한 로컬 환경 변수에 보관하세요. 브라우저로 전달되는 소스 코드, 저장소 또는 파이프라인 입력에 넣지 마세요.

전송 오류와 실행 실패를 구분해야 합니다. 요청이 인증되지 않았거나 유효하지 않거나 필요한 크레딧을 예약할 수 없다면 실행이 시작되기 전에 실패할 수 있습니다. 성공적으로 만든 실행도 나중에 failed로 끝날 수 있으므로 error_message를 확인하세요. 상태가 completed일 때만 에셋 URL을 사용합니다.

이미지에서 시작하는 워크플로라면 SDK에 문서화된 에셋 흐름으로 이미지를 업로드하거나 참조하고, 실용적인 이미지-투-비디오 가이드에서 원본 준비와 움직임 프롬프트를 확인하세요.