English Arabic Français Deutsch 日本語 한국어 Português Русский Español

Novita AI의 Wan 2.7 VideoEdit API: 프롬프트와 참조 이미지로 기존 클립 편집하기

작성자 / / Video, API / 6 분 읽기
Novita AI의 Wan 2.7 VideoEdit API: 프롬프트와 참조 이미지로 기존 클립 편집하기
목차
  1. Wan 2.7 VideoEdit을 사용해야 하는 경우
  2. 확인된 엔드포인트 및 워크플로
  3. 1단계: Novita AI API 키 받기
  4. 2단계: 요청 형식 이해하기
  5. 3단계: 첫 번째 VideoEdit 요청 제출하기
  6. 4단계: 작업 결과 엔포인트 폴링하기
  7. 5단계: 더 세밀한 시각적 제어가 필요할 때 참조 이미지 추가하기
  8. 실제로 신경 써야 할 주요 매개변수
  9. 문서화된 제한 사항 및 실질적 제약 조건
  10. Python 예제: 제출 및 폴링
  11. 셸 폴링을 포함한 cURL 예제
  12. 가격, 크레딧 및 비용 추정 전 확인 사항
  13. 일반적인 통합 실수
  14. 어떤 Wan 2.7 엔드포인트를 선택해야 하나요?
  15. FAQ
  16. 추천 문서

Novita AI의 Wan 2.7 VideoEdit은 이미 촬영된 영상이 있고 모델이 처음부터 모션을 재구축하지 않고 장면을 리스타일링하거나 다시 작성하도록 하려는 경우에 적합한 엔드포인트입니다. 소스 비디오를 POST https://api.novita.ai/v3/async/wan2.7-videoedit에 제출하면 task_id를 받고, 편집된 클립이 준비될 때까지 GET /v3/async/task-result를 폴링합니다. 이 가이드에서는 정확한 요청 형식, 참조 이미지를 추가해야 하는 경우, 그리고 프로덕션에 연결하기 전에 중요한 구현 세부 사항을 보여줍니다.

더 넓은 모드 비교는 Novita AI의 Wan 2.7: 텍스트-투-비디오 vs 이미지-투-비디오 vs 참조-투-비디오를 참조하세요.

Wan 2.7 VideoEdit을 사용해야 하는 경우

소스 클립의 타이밍과 카메라 움직임이 이미 충분히 좋고, 샷의 구성 방식이 아니라 시청자가 보는 내용을 AI로 변경하려는 경우 Wan 2.7 VideoEdit을 사용하세요.

일반적인 적합 사례:

  • 실사 클립이 있고 이를 애니메이션, 시네마틱 또는 스타일화된 렌더링으로 변환하려는 경우.
  • 원래 모션 호를 유지하면서 의상, 환경, 소품 또는 분위기를 변경해야 하는 경우.
  • 푸티지에 프롬프트 기반 변환을 적용하고 선택적으로 참조 이미지로 모양을 고정하려는 경우.

다음의 경우에는 적합한 엔드포인트가 아닙니다:

  • 텍스트만으로 완전히 새로운 모션이 필요한 경우. 대신 Wan 2.7 T2V를 사용하세요.
  • 정지 이미지를 애니메이트하려는 경우. 대신 Wan 2.7 I2V를 사용하세요.
  • 생성된 장면에 걸쳐 명명된 참조 슬롯이 있는 다중 캐릭터 롤플레이가 필요핚 경우. 대신 Wan 2.7 R2V를 사용하세요.

이 구분이 중요한 이유는 VideoEdit이 입력 클립에서 시작하기 때문입니다. 원래 모션이 잘못된 경우, 모델이 안무를 수정해 주지 않습니다.

확인된 엔드포인트 및 워크플로

Novita AI의 Wan 2.7 VideoEdit은 하나의 제출 엔드포인트와 공유 비동기 작업-결과 엔드포인트를 사용합니다:

필드 값
제출 엔드포인트 POST https://api.novita.ai/v3/async/wan2.7-videoedit
결과 폴링 GET https://api.novita.ai/v3/async/task-result?task_id=<id>
인증 헤더 Authorization: Bearer $NOVITA_API_KEY
콘텐츠 유형 application/json
공식 문서 Wan 2.7 VideoEdit API 참조

API는 비동기식입니다. 성공핚 제출 호출은 완료된 비디오 URL이 아닌 task_id를 반환합니다. 애플리케이션은 해당 작업 ID를 유지하고 이를 중심으로 폴링 또는 백그라운드 작업 로직을 구축해야 합니다.

1단계: Novita AI API 키 받기

Novita AI 키 관리에서 키를 생성하고 환경 변수에 보관하세요:

export NOVITA API_KEY="your_api_key_here"

키를 브라우저 코드, 모바일 앱 또는 체크인된 설정 파일에 하드코딩하지 마세요.

2단계: 요청 형식 이해하기

Wan 2.7 VideoEdit은 평평한 JSON 본문을 사용합니다. 요청은 필드를 input이나 parameters 아래에 중첩시키지 않습니다.

최소한 다음을 전송하세요:

  • video_url
  • prompt

문서화된 선택적 필드 중 일반적으로 먼저 신경 써야 하는 것은:

  • reference_image_url (룩/스타일에 대한 참조)
  • resolution
  • duration
  • audio_setting
  • prompt_extend
  • seed

3단계: 첫 번째 VideoEdit 요청 제출하기

이것은 가장 실용적인 최소 요청입니다:

curl -s -X POST https://api.novita.ai/v3/async/wan2.7-videoedit \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-type: application/json" \
  -d '{
    "video_url": "https://example.com/source-clip.mp4",
    "prompt": "이 사무실 복도 장면을 네온 사이버펑크 복도로 바꾸고, 걷는 동작과 카메라 경로는 유지하세요",
    "resolution": "720P",
    "duration": 5
  }'

예상 응답:

{
  "task_id": "abc123..."
}

제출 시점에 다른 것은 보자되지 않습니다. 요청을 동기 편집 응답이 아닌, 작 접수 단계로 간주하세요.

4단계: 작업 결과 엔포인트 폴링하기

반환된 task_id를 공유 작업-결과 API와 함께 사용하세요:

curl -s "https://api.novita.ai/v3/async/task-result?task_id=abc123..." \
  -H "Authorization: Bearer $NOVITA_API_KEY"

다음 상태를 기준으로 구축하세요:

상태 의미
TASK_STATUS_QUEUED 접수 및 실행 대기 중
TASK_STATUS_PROCESSING 편집 진행 중
TASK_STATUS_SUCCEED 편집된 비디오 준비 완료
TASK_STATUS_FAILED 작업 실패, 응답 본문 확인

작업이 성공하면 응답에는 편집된 출력 URL과 URL TTL이 포함된 videos 배열이 포함됩니다. 해당 자산을 호스팅된 URL을 영구 저장소로 취급하지 말고 신속하게 다운로드하거나 이동하세요.

5단계: 더 세밀한 시각적 제어가 필요할 때 참조 이미지 추가하기

reference_image_url은 선택 사항이지만 유용한 방식으로 편집 동작을 변경합니다.

다음 경우에 사용하세요:

  • 최종 클립이 특정 캐릭터 룩, 의상 또는 팔레트를 따르길 원할 때.
  • 텍스트 프롬프트에 모든 것을 맡기는 대신 출력을 특정 아트 방향으로 유도하려 할 때.
  • 소스 비디오 모션은 정확하지만 장면의 정체성이 텍스트만으로는 너무 느슨할 때.

참조 이미지를 사용한 예제 요청:

curl -s -X POST https://api.novita.ai/v3/async/wan2.7-videoedit \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/source-clip.mp4",
    "reference_image_url": "https://example.com/reference-look.png",
    "prompt": "같은 댄스 타이밍을 유지하면서 공연자를 참조 이미지의 룩과 색상 팔레트로 변환하세요",
    "resolution": "1080P",
    "duration": 6,
    "audio_setting": "auto"
  }'

결과가 계속 표류한다면, 일반적인 해결책은 더 긴 프롬프트가 아니라 더 구체적인 프롬프트와 더 좋은 참조 이미지입니다.

실제로 신경 써야 할 주요 매개변수

매개변수 유형 필수 설명
video_url string 예 편집할 소스 비디오
prompt string 예 목표 변환 설명
reference_image_url string 아니요 룩 및 스타일 기준을 위한 참조 이미지
resolution string 아니요 출력 해상도, 문서화된 값에는 720P 및 1080P 포함
duration integer 아니요 목표 출력 길이(초). 0은 입력 비디오 전체 길이 유지
audio_setting string 아니요 오디오 생성 동작 제어
prompt_extend boolean 아니요 모델이 짧은 프롬프트를 자동으로 확장하도록 함
seed integer 아니요 재시도 간 재현성 향상

기본값을 가정하기 전에 공식 매개변수 참조를 확인하세요. 비디오 모델 필드는 텍스트 모델 필드보다 더 자주 변경되며, 출력 제약 조건은 기억에 의존하면 잘못되기 쉽습니다.

문서화된 제한 사항 및 실질적 제약 조건

2026년 7월 29일 기준, Wan 2.7 VideoEdit에 대한 Novita의 공식 문서는 다음 경계를 문서화하고 있습니다:

  • 지원 해상도: 720P 및 1080P
  • duration 기본값은 0이며, 이는 입력 비디오 전체 길이를 의미합니다. 설정 시 문서화된 명시적 출력 지속 시간 범위는 2초에서 10초입니다.
  • 입력 비디오 형식: mp4 및 mov
  • 입력 비디오 크기 제한: 최대 100 MB
  • 참조 이미지 형식: jpg, jpeg, png, webp
  • 참조 이미지 크기 제한: 최대 20 MB
  • 출력 비디오 형식: mp4

이러한 제약 조건은 일반적인 미디어 파이프라인을 구축할 때 놓치기 쉽습니다. 가장 흔한 통합 실패는 엔드포인트가 허용하는 것보다 더 길거나 큰 소스 파일을 보내는 것입니다.

두 가지 실질적 시사점:

  1. 편집된 클립이 소스 길이를 유지하게 하려면 duration을 생략하거나 0으로 설정하고 2-10초 트림을 강제하지 마세요.
  2. 프롬프트를 빠르게 테스트하는 경우 먼저 720P를 사용하고 변환이 제대로 작동할 때만 1080P로 이동하세요.

Python 예제: 제출 및 폴링

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def submit_video_edit(
    video_url: str,
    prompt: str,
    reference_image_url: str | None = None,
    resolution: str = "720P",
    duration: int = 0,
    audio_setting: str = "auto",
    prompt_extend: bool = True,
    seed: int | None = None,
) -> str:
    payload = {
        "video_url": video_url,
        "prompt": prompt,
        "resolution": resolution,
        "duration": duration,
        "audio_setting": audio_setting,
        "prompt_extend": prompt_extend,
    }
    if reference_image_url:
        payload["reference_image_url"] = reference_image_url
    if seed is not None:
        payload["seed"] = seed

    resp = requests.post(
        f"{BASE_URL}/v3/async/wan2.7-videoedit",
        headers=HEADERS,
        json=payload,
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()["task_id"]


def poll_result(task_id: str, interval: int = 5, timeout: int = 300) -> dict:
    deadline = time.time() + timeout
    while time.time() < deadline:
        resp = requests.get(
            f"{BASE_URL}/v3/async/task-result",
            headers=HEADERS,
            params={"task_id": task_id},
            timeout=60,
        )
        resp.raise_for_status()
        data = resp.json()
        status = data.get("task", {}).get("status")

        if status == "TASK_STATUS_SUCCEED":
            return data
        if status == "TASK_STATUS_FAILED":
            reason = data.get("task", {}).get("reason", "unknown")
            raise RuntimeError(f"Task {task_id} failed: {reason}")

        time.sleep(interval)

    raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")


if __name__ == "__main__":
    task_id = submit_video_edit(
        video_url="https://example.com/source-clip.mp4",
        prompt="거리 장면을 비 내리는 레트로-미래주의 도시 밤으로 변경하고, 원래의 트래킹 샷은 유지하세요",
        reference_image_url="https://example.com/reference-frame.png",
        resolution="720P",
        duration=0,
        seed=42,
    )
    print(f"Submitted task: {task_id}")

    result = poll_result(task_id)
    video = result["videos"][0]
    print("Edited video URL:", video["video_url"])
    print("URL TTL:", video["video_url_ttl"])

셸 폴링을 포함한 cURL 예제

TASK_ID=$(curl -s -X POST https://api.novita.ai/v3/async/wan2.7-videoedit \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/source-clip.mp4",
    "prompt": "클립을 손으로 그린 애니메이션 도시 장면으로 변환하고, 달리는 동작은 유지하세요",
    "resolution": "720P",
    "duration": 0,
    "prompt_extend": true
  }' | jq -r '.task_id')

while true; do
  RESULT=$(curl -s "https://api.novita.ai/v3/async/task-result?task_id=$TASK_ID" \
    -H "Authorization: Bearer $NOVITA_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.task.status')

  if [ "$STATUS" = "TASK_STATUS_SUCCEED" ]; then
    echo "$RESULT" | jq -r '.videos[0].video_url'
    break
  fi

  if [ "$STATUS" = "TASK_STATUS_FAILED" ]; then
    echo "$RESULT"
    break
  fi

  sleep 5
done

백엔드 서비스에서 통합하는 경우, 전체 생성 시간 동안 사용자 요청을 열어두지 말고 이 폴링 루프를 워커에 래핑하세요.

가격, 크레딧 및 비용 추정 전 확인 사항

Novita AI는 모델 및 가격 페이지에서 비디오 모델의 가격을 공개하지만, 이 수치는 변경될 수 있습니다. Wan 2.7 VideoEdit의 경우, 고객 대상 비용 추정치를 게시하기 전에 Novita AI 가격 페이지 및 공식 문서에서 링크된 모델 항목에서 현재 요금을 직접 확인하세요.

엔지니어링 계획을 위한 보다 안전한 가정은 다음과 같습니다:

  • 비용은 단일 평면 요청 수수료가 아니라 생성된 클립 설정에 따라 확장됩니다.
  • 1080P 실행은 반복을 위한 잘못된 기준입니다.
  • 짧은 클립은 검증이 더 쉽고 디버깅 비용이 저렴합니다.

내부 도구를 구축하는 경우 가격 책정 조회를 코드에 상수로 포함된 것이 아니라 구성 문제로 취급하세요.

일반적인 통합 실수

도달 가능한 URL 대신 원시 업로드 보내기. 문서화된 요청 형식은 URL 기반 미디어 입력을 예상합니다. 소스 클립이 서버가 참조할 수 있는 안정적인 URL에 이미 있는지 확인하세요.

비디오 편집을 모션 변경에 사용하는 경우. VideoEdit은 변환 엔드포인트이지 안무 엔드포인트가 아닙니다. 원래 움직임이 잘못된 경우 T2V 또는 I2V로 다시 생성하세요.

소스 비디오와 참조 이미지 제한 혼동. 소스 비디오는 더 큰 자198로, mp4/mov, 최대 100MB입니다. 20MB 더 작은 제한은 reference_image_url에 적용되며 video_url이 아닙니다.

너무 공격적으로 폴링하기. 다중 초 비디오 작업에 매초 작업-결과 엔드포인트를 호출하는 것은 필요하지 않습니다. 5-10초 간격이 일반적으로 더 좋은 시작점입니다.

URL TTL 무시. 결과 URL은 임시입니다. 편집된 클립이 다운스트림에 중요한 경우 자산을 신속하게 영구 저장하세요.

프롬프트 구체성 생략. "더 좋게 만들어 줘"는 편집 프롬프트가 아닙니다. 대상 스타일, 환경, 주제 처리, 변경되지 않아야 할 모션을 설명하세요.

어떤 Wan 2.7 엔드포인트를 선택해야 하나요?

이 빠른 규칙을 사용하세요:

  • 이미 소스 비디오가 있을 때는 VideoEdit 을 선택하세요.
  • 소스 이미지가 있거나 스틸 중심 워크플로에서 연속성을 원할 때는 I2V 를 선택하세요.
  • 텍스트만 있을 때는 T2V 를 선택하세요.
  • 정체성 일관성과 참조 캐릭터 제어가 기존 클립 편집보다 중요할 때는 R2V 를 선택하세요.

이 구분이 통합을 단순하게 유지합니다. 팀은 종종 실제로 프롬프트 기반 편집 문제인 작업에 텍스트-투-비디오를 과도하게 사용합니다.

이 엔드포인트 주변에서 오케스트레이션을 연결하는 경우, 더 높은 가중치 모델 앵커를 위해 Macaron V1 Tall Quick Start on Novita AI 및 Qwen3.8-Max on Novita AI를 비교하세요.

FAQ

Novita AI에서 Wan 2.7 VideoEdit의 엔드포인트는 무엇인가요?

POST https://api.novita.ai/v3/async/wan2.7-videoedit. task_id를 반환한 다음, GET https://api.novita.ai/v3/async/task-result?task_id=<id>를 폴링하여 완료를 확인합니다.

소스 비디오와 함께 참조 이미지를 제공할 수 있나요?

네. 문서화된 요청 형식은 video_url 및 prompt와 함께 선택적 reference_image_url을 지원하며, 이는 최종 룩을 더 세밀하게 조정하는 데 유용합니다.

Novita AI에서 Wan 2.7 VideoEdit이 지원하는 비디오 길이는 얼마인가요?

2026년 7월 29일 기준으로 문서화된 바에 따르면 duration은 기본적으로 0이며, 이는 입력 비디오 전체 길이를 의미합니다. duration을 명시적으로 설정하면 문서화된 범위는 2-10초입니다.

Wan 2.7 VideoEdit은 큰 소스 비디오를 허용하나요?

네, 문서화된 제한 내에서 가능합니다. 공식 문서에는 mp4/mov 입력이 최대 100MB라고 나와 있112. 별도의 20MB 제한은 선택적 참조 이미지에 적용됩니다.

Wan 2.7 VideoEdit 또는 Wan 2.7 I2V를 사용해야 하나요?

이미 클립이 있고 변환하려는 경우 VideoEdit을 사용하세요. 시작점이 정지 이미지 또는 이미지 중심 워크플로인 경우 I2V를 사용하세요.

추천 문서

관련 게시글