hiapi API로 flux-3를 사용하여 AI 비디오 편집하는 방법

여기서 "편집"은 특정한 의미를 갖습니다. flux-3(FLUX.3 Video, Black Forest Labs 제작)는 기존 클립을 확장하여—그 움직임, 카메라 움직임, 사운드를 이어가며—새로운 화면을 생성하거나, 순서가 있는 키프레임 이미지 세트를 기반으로 하나의 샷을 구성합니다. 기존 소재를 자르거나, 컷편집하거나, 마스킹하거나, 색보정하거나, 그 밖의 인플레이스 처리를 하지는 않습니다. 편집기를 찾아 오셨다면, 아래 FAQ가 코드를 작성하기 전에 flux-3가 정말 적합한지 가장 빠르게 판단하는 방법입니다.

정말 잘하는 것은: 이미 가진 영상을 가져와 동일한 피사체, 카메라 언어, 오디오를 유지하며 이어지는 영상을 생성하는 것—너무 일찍 끝난 샷을 늘리거나, 여러 생성된 클립을 더 긴 샷으로 이어 붙이는 데 적합합니다. 다른 모드는 정적 이미지 세트를 순서 있는 키프레임으로 받아 그 사이의 움직임을 생성합니다. 이는 스토리보드 기반 편집과 같지만, 기존 영상은 전혀 관여하지 않습니다.

1. 필요한 것

대시보드에서 발급받은 hiapi API 키(sk-...)입니다. flux-3는 다른 모든 hiapi 모델과 마찬가지로 통합 task API를 통해 호출되므로 여기에 모델 전용 설정은 없습니다—다른 hiapi 비디오 모델을 호출해 본 적이 있다면 준비는 이미 끝난 것입니다.

2. 최소 실행 예제

작업을 생성한 다음 종료 상태에 도달할 때까지 폴링합니다(또는 콜백 사용—프로덕션 패턴 참고).

# 1. 创建任务——延续模式（start_video）
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3",
    "input": {
      "prompt": "继续平移，镜头继续向右漂移，保持相同光照",
      "start_video": "https://your-cdn.example.com/source-clip.mp4",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "generate_audio": true
    }
  }'
# -> {"data": {"id": "task_...", "status": "pending"}}

# 2. 轮询直到终止
curl -s https://api.hiapi.ai/v1/tasks/task_... \
  -H "Authorization: Bearer sk-<your-key>"
# -> {"data": {"id": "task_...", "status": "succeeded",
#              "output": [{"url": "https://...mp4", "expireAt": "..."}]}}

start_video는 MP4를 가리키는 공개 HTTPS URL입니다(소스 소재 최대 50MB 및 15초)—이것이 flux-3가 이어가는 클립입니다. duration은 5~20초의 정수이며, 합성된 출력 길이가 아니라 새로 생성되는 클립의 길이를 제어합니다. resolution은 720p 또는 1080p이며, aspect_ratio는 auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, 9:16을 받습니다. generate_audio는 불리언이며—true일 때 모델이 생성한 환경음이 별도 오디오 파일이 아니라 출력 MP4에 직접 구워집니다. 프롬프트를 반복 조정할 때는 draft: true를 설정하세요. 드래프트 작업은 더 저렴하지만 resolution을 720p로만 강제합니다(draft: true와 resolution: "1080p"를 함께 담은 요청은 거부됩니다).

키프레임 스토리보드(기존 소재 편집이 아님)

다른 입력 모드는 start_video 대신 image_urls를 사용합니다—1~10개의 이미지 URL을 담은 순서 있는 배열로, flux-3가 이를 스토리보드로 간주하고 순서대로 연결하는 움직임을 생성합니다:

{
  "model": "flux-3",
  "input": {
    "prompt": "平滑地推轨依次穿过每个场景",
    "image_urls": [
      "https://your-cdn.example.com/keyframe-1.jpg",
      "https://your-cdn.example.com/keyframe-2.jpg",
      "https://your-cdn.example.com/keyframe-3.jpg"
    ],
    "duration": 8,
    "resolution": "720p"
  }
}

image_urls와 start_video는 같은 모델에서 서로 다른 두 가지 작업 형태입니다—한 요청에 둘 다 보내지 마세요. 정적 이미지로부터 샷을 처음부터 구성할 때는 image_urls를 사용하고, 이미 가진 생성(또는 소스) 소재를 앞으로 이어가고 싶을 때는 start_video를 사용하세요.

3. 프로덕션 패턴

규모가 커지면 폴링 대신 콜백을 사용하세요. 루프에서 폴링하는 대신 같은 요청 본문에 callback 객체를 전달하세요:

{
  "model": "flux-3",
  "input": { "...": "..." },
  "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
}

when: "final"은 작업이 임의의 종료 상태에 도달할 때 한 번만 트리거됩니다—succeeded와 failed 모두 종료 상태이므로, 콜백이 곧 성공을 뜻한다고 가정하지 말고 taskId로 webhook 핸들러를 중복 제거하세요. GET /v1/tasks/:id 폴링은 로컬 디버깅, 저빈도 일회성 작업, 또는 콜백이 도착하지 않았을 때의 대사 폴백에 더 적합합니다.

멱등성. 주의하지 않으면 타임아웃이나 연결 끊김 후의 재시도가 중복(과금되는) 작업을 만들 수 있습니다—생성 호출이 반환한 작업 id를 추적하고, 새 작업을 제출하기 전에 재시도를 해당 id에 대한 GET으로 바꾸세요.

출력 URL은 만료됩니다. 각 출력 항목의 expireAt 필드는 장식이 아닙니다—콜백이든 폴링이든 작업 성공을 확인하는 즉시 영상을 다운로드하여 자체 스토리지에 영속화하세요.

인증 실패. 잘못되었거나 누락된 키는 {"error": {"code": "permission_denied", ...}} 내용의 HTTP 401을 반환합니다. 어떤 비 2xx든 생성 자체의 실패라고 가정하지 말고 해당 상태/코드를 명시적으로 확인하세요—"내 키가 틀렸다"와 "모델이 내 입력을 거부했다"는 서로 다른 해결책이 필요합니다.

제출 전에 미디어 URL을 검증하세요. start_video와 image_urls는 타입과 형식을 검사하지만 해당 URL의 파일이 실제로 존재하거나 디코딩 가능한지는 검사하지 않습니다—문법적으로 유효하지만 깨진 URL은 여전히 작업을 생성하고, 제출 시 거부되지 않고 몇 초 실행된 후 실패합니다. URL을 배치 작업에 연결하기 전에 실제로 해석되는지 확인하세요.

4. 관련 페이지

• flux-3 모델 페이지—전체 매개변수 참조, 플레이그라운드, 그리고 세 가지 모드(텍스트→비디오, 키프레임 스토리보드, 연속) 모두의 현재 초당·해상도별 가격.
• 작업 생성 문서—콜백 옵션을 포함한 전체 /v1/tasks 요청/응답 참조.
• 인증 문서—Authorization: Bearer sk-... 헤더와 키 스코프가 동작하는 방식.
• AI 비디오의 첫/마지막 프레임 제어—flux-3의 다중 키프레임 스토리보드 모드가 샷에 충분히 정교하지 않을 때, 두 정적 이미지 사이를 보간하는 모델에 적합한 관련 접근법.
• hiapi 가격—현재 요율(연속은 표준 생성보다 비싸고, 드래프트 모드는 둘 다보다 저렴합니다—하드코딩된 숫자가 아니라 실시간 페이지를 확인하세요).

5. FAQ

flux-3가 기존 영상을 자르거나, 컷편집하거나, 마스킹하거나, 색보정할 수 있나요? 아니요. flux-3의 "비디오→비디오" 모드는 연속입니다—소스 클립의 피사체, 카메라 움직임, 사운드를 이어가는 새로운 화면을 생성합니다. 이미 존재하는 프레임을 수정하지는 않습니다. 현재 어떤 hiapi 모델도 비디오에 대한 타임라인식 자르기/컷편집이나 영역 마스킹 편집을 할 수 없습니다.

연속과 키프레임 스토리보드의 차이는 무엇인가요? 연속(start_video)은 기존 영상 파일이 필요하고それを 확장합니다. 키프레임 스토리보드(image_urls)는 정적 이미지만 필요로 하고 그 사이의 움직임을 생성합니다—소스 영상이 필요 없습니다. 동일한 flux-3 모델 id에서 상호 배타적인 입력입니다.

한 요청에 start_video와 image_urls를 함께 사용할 수 있나요? 아니요—작업마다 한 가지 모드를 선택합니다. 둘 다 보내는 것은 지원되는 입력 형태가 아닙니다.

draft: true가 연속 모드에서도 동작하나요? 네, 그리고 전체 해상도 실행을 제출하기 전에 연속 프롬프트를 반복 조정하는 더 저렴한 방법입니다—하지만 표준 모드와 마찬가지로 드래프트 연속도 720p로 제한됩니다.

왜 제 작업이 평소 생성 시간을 들이지 않고 거의 순식간에 실패하나요? 가장 흔한 원인은 start_video 또는 image_urls 항목이 요청 시점에 실제로 유효한 파일로 해석되지 않기 때문입니다—API는 문법적으로 올바른 URL을 동기적으로 가져오지 않고 수용하므로, 깨진 링크는 사전 검증 오류가 아니라 빠른 failed 상태로 나타납니다.

연속 모드에서 소스 클립은 얼마나 길 수 있나요? MP4 형식으로 최대 15초 및 50MB입니다. 더 길거나 큰 소스 파일은 start_video 입력으로 허용되지 않습니다.