동영상 생성

검색 /

동영상 모델은 한 번의 응답이 아니라 작업으로 답합니다. POST /v1/videos는 작업 ID와 "status": "queued"를 반환하고, GET /v1/videos/{task_id}로 작업이 completed 또는 failed가 될 때까지 진행 상황을 확인합니다. 완료되면 결과물은 metadata.url에 담긴 서명된 URL입니다. 이 URL에는 Expires 파라미터가 있으므로 링크를 저장하지 말고 파일을 내려받으세요. 실패한 작업은 업스트림 오류 코드와 메시지를 error.code와 error.message에 담으므로 요청에서 어떤 필드가 빠졌는지 대개 바로 알 수 있습니다. POST /v1/video/generations도 같은 핸들러로 연결되어, 해당 경로로 이미 구현한 클라이언트를 그대로 쓸 수 있습니다.

POST /v1/videos

curl https://api.chinaapi.ai/v1/videos \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-i2v",
    "prompt": "the cat turns and walks toward the camera",
    "input_reference": "https://example.com/first-frame.jpg",
    "size": "1280*720",
    "duration": 5
  }'

# {"id":"task_9f2c...","task_id":"task_9f2c...","object":"video",
#  "model":"wan2.7-i2v","status":"queued","progress":0}

GET /v1/videos/{task_id}

curl https://api.chinaapi.ai/v1/videos/task_9f2c... \
  -H "Authorization: Bearer $CHINAAPI_KEY"

# {"id":"task_9f2c...","object":"video","model":"wan2.7-i2v",
#  "status":"completed","progress":100,
#  "metadata":{"url":"https://.../output.mp4?Expires=..."}}

텍스트로 만들기

wan2.7-t2v

필수 필드는 model과 prompt뿐입니다. size와 duration을 생략하면 게이트웨이가 1280*720, 5초로 제출합니다.

이미지로 만들기

wan2.7-i2v

정지 이미지를 움직이게 합니다. input_reference에 공개적으로 접근할 수 있는 이미지 URL을 넣으면 그것이 첫 프레임이 되며, size와 duration을 함께 보내세요.

참조에서 동영상

wan2.7-r2v

참조 소재로 동영상을 만듭니다. input_reference는 참조 이미지 한 장을 받습니다. 여러 장을 보내려면 images를 쓰고, video_url로 참조 동영상을 추가합니다 — 참조는 합쳐서 최대 5개입니다. input_reference와 images를 함께 보내지 마세요. 게이트웨이는 input_reference만 남깁니다.

동영상 편집

wan2.7-videoedit

프롬프트로 기존 클립을 편집합니다. video_url에는 원본 영상을 넣습니다. 원본은 2~10초 길이의 MP4 또는 MOV여야 하며, 출력은 size로 정해집니다.

30초 동영상

doubao-seedance-2-5-260628

참조 이미지는 images에 넣고, input_reference는 한 장을 받습니다. 둘 다 보내면 둘 다 전달됩니다. 길이는 seconds 또는 duration에, 공급자 파라미터는 metadata에 넣고, resolution은 480p 또는 720p만 가능합니다.

Seedance 2.0

doubao-seedance-2-0-260128

요청 형태는 doubao-seedance-2-5-260628과 같고 metadata.content의 role 규칙도 그대로 적용됩니다. doubao-seedance-2-0-fast-260128과 doubao-seedance-2-0-mini-260615는 품질을 내주고 속도와 비용을 얻습니다. 또한 2.0 계열은 이미지나 동영상 참조가 최소 하나 필요하며, 2.5처럼 오디오만 넣는 입력은 받지 않습니다.

Kling 3.0

kling-v3

첫 프레임은 image에 넣습니다. 이 계열은 input_reference를 전혀 읽지 않습니다. mode의 기본값은 std, duration의 기본값은 5초입니다. 나머지는 metadata가 맡습니다 — 마지막 프레임용 image_tail, on 또는 off를 받는 sound(기본값 off), 그리고 negative_prompt, cfg_scale, camera_control입니다.

보급형 등급

kling-3.0-turbo

텍스트로 동영상을 만들려면 prompt만 보내고, 첫 프레임을 쓰려면 image를 더하면 업스트림이 요구하는 contents 배열은 게이트웨이가 만들어 줍니다. 크기 관련 값은 metadata.settings 아래에 있습니다. resolution은 720p 또는 1080p, duration은 3~15초, aspect_ratio는 16:9·9:16·1:1 중 하나입니다. 오디오는 항상 포함되며 끄는 스위치가 없습니다.

다중 이미지 참조

kling-v3-omni

여러 장의 참조 이미지를 한 번에 사용해 생성합니다. 모든 파라미터는 metadata 안에 있고 resolution 필드는 없습니다 — 품질 등급은 mode입니다. 아래의 실제 예시를 참고하세요.

네이티브 오디오

MiniMax-H3

게이트웨이 자체 필드를 받아 업스트림 페이로드를 대신 조립합니다. image 또는 input_reference는 첫 프레임이 되고, images는 참조 이미지, video_url은 참조 동영상이 됩니다. size로 768P나 2K를 고르고 duration은 4에서 15 사이의 정수입니다. 텍스트만 있는 요청에는 adaptive가 아닌 metadata.ratio를 명시해야 합니다.

Hailuo

MiniMax-Hailuo-2.3

MiniMax-Hailuo-2.3-Fast, MiniMax-Hailuo-02도 마찬가지입니다. 이들이 최상위에서 읽는 값은 prompt, duration, size뿐이고, 이미지는 모두 metadata를 거쳐 first_frame_image, last_frame_image, subject_reference 중 하나로 전달해야 합니다.

480P 지원

happyhorse-1.1-t2v

happyhorse-1.1-i2v, happyhorse-1.1-r2v도 같습니다. 필드는 wan2.7 계열과 동일한 prompt, input_reference, size, duration이고, 여기서는 480P에도 가격이 있어 wan2.7이 거부하는 832*480이 통과합니다. 참조를 여러 개 넘길 때는 metadata.input.media에 넣으세요. images 필드가 일으키는 자동 조립은 wan2.7-r2v 전용입니다.

팁 크기는 너비와 높이를 별표로 이어 1280*720처럼 씁니다. x는 쓸 수 없습니다. 832x480은 invalid size: 832x480, example: 1920*1080을 돌려줍니다. duration은 초 단위 정수입니다. wan2.7-i2v, wan2.7-r2v, wan2.7-videoedit에서는 게이트웨이가 size를 해상도 등급으로 접고 업스트림에는 두 등급뿐이므로 720P에는 1280*720, 1080P에는 1920*1080을 보내세요. 832*480 같은 480P 크기는 이 세 모델에 가격이 없어서 즉시 거부되거나, 일단 접수된 뒤 업스트림에서 InvalidParameter로 실패합니다. 실패한 작업은 환불되지만 어느 쪽이든 왕복은 헛수고가 됩니다. wan2.7-t2v는 값을 쓴 그대로 받습니다.

팁 Kling 계열은 size에서 화면비를 읽지만, 그 대응표는 크기를 x로 씁니다 — 1280x720, 1920x1080, 720x1280, 1080x1920, 1024x1024, 512x512 — 그리고 표에 없는 값은 오류 없이 1:1이 됩니다. 따라서 kling-v3에 별표 형식 1280*720을 보내면 항의가 아니라 정사각형 영상이 돌아옵니다. 화면 구도가 중요하면 metadata.aspect_ratio를 직접 지정하세요.

팁 MiniMax-Hailuo-2.3, MiniMax-Hailuo-2.3-Fast, MiniMax-Hailuo-02은 최상위의 image, input_reference, images, video_url을 아무 말 없이 버립니다. 요청은 성공하지만 텍스트-투-비디오로 실행되고 그 기준으로 과금됩니다. 이미지는 metadata.first_frame_image에 넣고, 마지막 프레임은 metadata.last_frame_image, 인물 참조는 metadata.subject_reference를 쓰세요. MiniMax-H3은 이 계열의 예외로 최상위 필드를 읽습니다.

kling-v3-omni · multi-image reference

curl https://api.chinaapi.ai/v1/video/generations \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "prompt": "the character from the references walks through a neon-lit street",
    "metadata": {
      "image_list": [
        {"image_url": "https://example.com/character.jpg"},
        {"image_url": "https://example.com/outfit.jpg"},
        {"image_url": "https://example.com/scene.jpg"}
      ],
      "mode": "std",
      "duration": "5",
      "aspect_ratio": "16:9",
      "sound": "off"
    }
  }'

GET /v1/video/generations/{task_id}

curl https://api.chinaapi.ai/v1/video/generations/task_9f2c... \
  -H "Authorization: Bearer $CHINAAPI_KEY"

# {"code":"success",
#  "data":{"task_id":"task_9f2c...","status":"SUCCESS",
#          "progress":"100%","fail_reason":"",
#          "result_url":"https://.../output.mp4"}}

팁 참조 이미지에는 type을 붙이지 않습니다. 이 필드는 first_frame이나 end_frame을 표시할 때만 쓰이고, 첫 프레임이 없으면 aspect_ratio가 필수입니다. mode는 품질 등급으로 std, pro, 4k 중 하나이며, 업스트림 기본값은 pro라서 표시 가격의 1.33배로, 4k는 5배로 과금됩니다. 예상한 금액대로 청구되게 하려면 mode를 명시하세요. duration은 "3"부터 "15"까지의 문자열이고 sound의 기본값은 off입니다. 참조 동영상은 video_list에 넣고 반드시 "refer_type": "feature"를 지정해야 합니다. 편집 모드인 base는 넘긴 영상 길이로 과금되어 제출 전에 가격을 낼 수 없으므로 거부됩니다. 참조 이미지에는 업스트림 쪽 최소 크기도 있습니다. 아이콘만 한 파일은 제출까지는 통과하지만 작업이 Image pixel is invalid로 실패합니다. 실패한 작업은 환불되지만 왕복은 헛수고가 됩니다.

팁 두 경로는 결과를 서로 다른 형태로 돌려줍니다. GET /v1/videos/{task_id}는 OpenAI 동영상 형식으로 답하며 파일은 metadata.url, 진행률은 숫자입니다. GET /v1/video/generations/{task_id}는 {"code": "success", "data": {…}}로 답하며 파일은 data.result_url, data.status는 SUCCESS나 FAILURE 같은 대문자 단어, data.progress는 "100%" 같은 문자열이고, 실패 사유는 data.fail_reason에 담깁니다. 제출한 쪽과 같은 경로로 조회하세요.

doubao-seedance-2-5-260628 · first frame

curl https://api.chinaapi.ai/v1/videos \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "prompt": "the subject slowly turns toward the camera",
    "images": ["https://example.com/first-frame.jpg"],
    "seconds": "5",
    "metadata": {"resolution": "480p"}
  }'

doubao-seedance-2-5-260628 · reference mode

curl https://api.chinaapi.ai/v1/videos \
  -H "Authorization: Bearer $CHINAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "prompt": "keep the subject from the reference image",
    "seconds": "5",
    "metadata": {
      "resolution": "480p",
      "ratio": "16:9",
      "content": [
        {
          "type": "image_url",
          "image_url": {"url": "https://example.com/reference.jpg"},
          "role": "reference_image"
        }
      ]
    }
  }'

팁 role이 없는 이미지는 참조가 아니라 첫 프레임으로 읽힙니다. 출력은 그 이미지의 화면비를 따르고, ratio를 함께 보내면 InvalidParameter.TaskTypeConstraint로 거부되며, 이 모드에서는 seconds 2도 거부됩니다(5는 됩니다). generate_audio는 업스트림 기본값이 true이므로 metadata에서 false로 두지 않으면 오디오 트랙이 포함된 파일이 돌아옵니다. metadata.content의 각 항목에 role을 달면 참조 모드 전체 — 이미지 30장, 동영상 10개, 오디오 10개까지, 오디오만 입력, 30초 연속 생성 — 를 쓸 수 있고 그곳에서는 ratio도 허용됩니다.