비디오 제작

모든 영상은 한 가지 호출로 시작합니다: POST /v1/render. 이 페이지는 그 통화에서 내리는 선택을 설명합니다. 모든 필드와 그 한계에 대해서는 Create render 참조를 참조하세요.

브리프 또는 장면 계획

이거 하나 보내.

브리핑

brief는 영상을 평이하게 설명한 것으로, 최대 4,000자까지 구성됩니다. Reigniter 장면을 계획하고, 내레이션을 작성하며, 렌더링을 시작합니다.

{
  "brief": "A 30 second advert for Northwind Coffee's weekly subscription. Show the beans, the roasting, and a happy customer opening the box.",
  "kind": "ad",
  "duration_sec": 30,
  "brand_name": "Northwind Coffee",
  "category": "coffee"
}

계획을 형성하는 필드:

필드	기본 설정	이 제품이 하는 일은
`kind`	`ad`	광고 `ad`, `training` 교육 영상 광고 때문이에요.
`duration_sec`	`ad`20, `training` 60	목표 총 시간, 5초에서 120초.
`narrator`	`true`	`false` 음성 없는 영상을 만듭니다.
`brand_name`	전혀 없습니다	플래너가 사용해야 할 브랜드명.
`category`	전혀 없습니다	예를 들어 `coffee` 또는 `saas` 같은 제품 범주 .
`title`	당신을 위해 쓴 글	영상 제목입니다.

계획 부서는 크레딧을 사용합니다. 계획이 실패하면 502 PLAN_FAILED 을 받고 계획 크레딧은 환불됩니다. plan_notes 담당자에게 다시 보내면, 계획자가 자신의 계획에서 지적한 내용을 설명해 줍니다.

장면 계획

scene_plan는 1개부터 12개까지의 장면 목록을 순서대로 렌더링한 것입니다. 각 장면이 무엇을 보여주고 무엇을 말해야 하는지 이미 알고 있을 때 사용하세요.

{
  "title": "Northwind launch",
  "scene_plan": [
    {
      "type": "motion",
      "role": "hook",
      "prompt": "Fresh coffee, delivered weekly",
      "script": "Fresh coffee, delivered every week.",
      "motion": { "beat": "hook" }
    },
    {
      "type": "t2v_fast",
      "role": "body",
      "prompt": "Slow close-up of coffee beans tumbling out of a kraft paper bag onto a wooden table, soft morning light",
      "script": "Roasted in small batches, a few days before it reaches you."
    },
    {
      "type": "motion",
      "role": "cta",
      "prompt": "Order at northwind.example",
      "script": "Order today.",
      "motion": { "beat": "cta" }
    }
  ]
}

장면 유형:

`type`	렌더링
`motion`	선명한 애니메이션 텍스트, 숫자, 단계, 로고 등. 읽기 쉬운 모든 것에 사용하세요.
`t2v_fast`	`prompt` 에서 생성된 사람, 장소 또는 물체의 영상.
`i2v_fast`	이미지에서 시작하는 생성된 영상: 장면의 `ref_image_url` 이나 제품 사진.
`s2v`	카메라를 향해 말하는 발표자. 얼굴이 필요해.
`walk_talk`	발표자가 걷고 말하는 거야. 얼굴이 필요해.
`footage`	`video_url` 에서 본인이 직접 만든 클립을 있는 그대로 재생하세요.

각 장면은 prompt (카메라가 보는 것, 또는 motion 화면 상의 복사본)과 선택적 script (내레이터의 대사)를 가져갑니다. 장면 필드의 전체 목록은 참고문헌에 있습니다.

브랜드

API 렌더링은 계정에 브랜드 키트가 있더라도 스스로 브랜드를 감지하지 않습니다. 각 요청에서 브랜드를 선택하세요:

brand_logo_url: 당신의 로고, 공개 https URL 또는 데이터 URI로서의 경우.
brand_colors: 선택 사항, 최대 12개의 육각형 색상(예: ["#3B2416", "#F4E9DC"]).

{
  "brief": "A 20 second advert for Northwind Coffee.",
  "brand_logo_url": "https://example.com/northwind-logo.png",
  "brand_colors": ["#3B2416", "#F4E9DC"]
}

로고가 없으면 영상은 로고도 끝도 없이 렌더링됩니다. 명확히 말하려면, brand_enabled: false 보내세요.

제품 사진

product_image_url 제품 사진(공개 https URL 또는 데이터 URI)입니다. 모델이 직접 만들어내지 않고 모든 장면에서 제품을 동일하게 유지합니다.

일부 포맷은 제품을 판매하며 사진을 요구합니다. 예를 들어 product-ad, unboxing, ugc-ad 또는 app-demo 같은 route을 설정하고 도면에 제품이 표시되면, 사진이 없는 렌더링은 400 PRODUCT_IMAGE_REQUIRED로 거부됩니다. 의도적으로 사진 없이 렌더링하려면 product_enabled: false 보내세요.

진행자

s2v 장면과 walk_talk 장면은 사람이 말하는 모습을 보여줍니다. 얼굴이 필요합니다: 영상 전체에 avatar_preset_id 있거나 장면에 ref_image_url 있어야 합니다. 대화 장면이 있고 얼굴이 없는 계획은 400 PRESENTER_REQUIRED 없습니다. Reigniter 기본 진행자를 사용하게 하려면 presenter_enabled: false 보내세요.

영상을 고정시키는 게 아무것도 없어요

route을 설정하고 브랜드도, 제품 사진도, 발표자도 없으며, 계획이 모든 사진을 생성하면 렌더링은 422 NO_ANCHOR 거부됩니다. 앵커가 없으면 모델이 제품과 사람을 만들어내고, 브랜드와 맞지 않습니다.

세 가지 중 하나를 추가하거나, 어쨌든 product_enabled: false 나 presenter_enabled: false 를 보내서 렌더링하세요.

외관과 사운드

필드	가치	기본 설정
`aspect`	`9:16`, `16:9`, `1:1`, `4:5`, `4:3`, `3:4`	`9:16`
`quality`	`draft`, `standard`, `premium`	`draft`
`language`	`en`, `fr`, `de` 같은 언어 코드입니다	`en`
`art_style`	`cinematic`, `stop_motion`, `mascot`, `watercolour`, `whimsy_3d`	`cinematic`
`music_style`	`upbeat-tech`, `cinematic-epic`, `lo-fi-chill`, `corporate-pop`	포맷에 의해 정해진
`voice_preset_id`	내레이터 음성 ID	기본 목소리
`upscale`	`true` 아니면 `false`	형식과 품질에 의해 결정됩니다

quality과 upscale가 높을수록 더 많은 크레딧이 들고 시간이 더 오래 걸립니다.

교육 영상

광고 대신 교육 영상을 계획할 수 있도록 brief과 함께 kind: "training" 설정하세요. 플래너는 동작과 요약을 작성하고, motion 장면을 화면 지시로 사용합니다.

{
  "brief": "How to reset a password in the Acme admin panel. Three steps, then a recap.",
  "kind": "training",
  "duration_sec": 60,
  "aspect": "16:9",
  "brand_logo_url": "https://example.com/acme-logo.png"
}

재시도와 놨등성

매번 렌더링할 때마다 UUID와 같은 고유 값의 Idempotency-Key 헤더를 보내세요. 요청이 타임아웃되고 같은 키로 다시 시도하면 Reigniter 반복을 거부하고 렌더링하거나 두 번째로 충전하지 않습니다.

반복은 거부되므로 원래 job_id을 반환하지 않습니다. 첫 번째 응답을 받을 때마다 job_id 을 저장하세요.
scene_plan가 있으면 반복은 409 DUPLICATE_REQUEST 돌아옵니다.
brief를 사용하면 반복은 메시지를 402 This request was already submitted 반환할 수 있습니다. 409 처럼 취급하세요.
새 영상마다 새 키를 사용하세요. 다른 영상에 키를 재사용하면 그 영상이 거부됩니다.

헤더가 없으면 모든 호출이 새로운 렌더와 새로운 차지가 됩니다.

워터마크

렌더 응답에는 watermarked 필드가 있습니다. Agency 계획에서 제작된 영상은 워터마크가 없습니다.

출력

작업이 성공하면 video_url GET /v1/job/{id} MP4에 직접 연결됩니다. 다운로드하여 직접 보관하세요.