동영상 모델고급 사용자업데이트
POST/v1/videos/generations

API 콘솔

POST/v1/videos/generations
키 보기

입력한 키로 실제 요청을 보내며 일반 API 요금이 적용됩니다.

Kling V3 Motion Control

요청 ID kling-v3-motion-control

프로토콜

인증

요청에는 API 키 관리의 API 키가 필요합니다. JSON 요청은 Content-Type: application/json을 지정하세요.

  • Authorization: Bearer YOUR_API_KEY

요청 매개변수

POST /v1/videos/generations

필드유형필수 여부설명
modelstring필수kling-v3-motion-control. 이 페이지에 표시된 모델 ID를 사용하세요.
promptstring선택캐릭터나 원하는 움직임을 설명할 수 있습니다.
contentarray<object>필수참조 이미지 한 장과 참조 동영상 한 개를 지정합니다.
content[].typestring필수사용 가능한 값은 text, image_url, input_image, video_url, input_video입니다.
content[].textstring조건부type: "text"인 항목에 프롬프트를 지정하세요.
content[].rolestring필수이미지에는 reference_image, 영상에는 reference_video를 사용합니다.
content[].asset_idstring조건부POST /v1/videos/assets에 소재를 업로드하고 반환된 id를 사용합니다. multipart에서 kind(image, video)를 file보다 먼저 보냅니다. 본인 계정의 미디어만 사용할 수 있습니다. 미디어 ID와 공개 HTTPS URL 중 하나를 사용합니다.
content[].image_urlstring조건부공개 HTTPS 이미지 URL을 문자열로 전달합니다.
content[].video_urlstring조건부공개 HTTPS 동영상 URL을 문자열로 전달합니다.
motion_modestring선택모션 제어 모드입니다. 사용 가능한 값은 std, pro입니다. 기본값은 std입니다.
character_orientationstring선택참조 영상은 image일 때 310초, video일 때 330초여야 합니다. 사용 가능한 값은 image, video입니다. 기본값은 image입니다.
keep_original_soundboolean선택참조 영상의 원본 오디오 유지 여부입니다. 기본값은 true입니다.

요청 예시

API Key를 로컬 환경 변수 ICODEEASY_API_KEY에 설정하고 직접 HTTP 호출을 허용하는 엔드포인트를 선택하세요. 특정 클라이언트가 필요한 경우 해당 설정 가이드를 따르세요.

예시의 미디어 URL 및 에셋 ID를 유효한 내 에셋으로 바꾸세요.

Video Generations

bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/generations' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "model": "kling-v3-motion-control",
  "prompt": "Preserve the character identity and follow the reference motion.",
  "content": [
    {
      "type": "image_url",
      "image_url": "https://example.com/reference.png",
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": "https://example.com/motion.mp4",
      "role": "reference_video"
    }
  ],
  "motion_mode": "std",
  "character_orientation": "image",
  "keep_original_sound": true
}'

영상 작업 조회

bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY"

영상 다운로드

bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID/content' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -L \
  -o result.mp4

완료된 영상 작업 삭제

bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -i \
  -X DELETE

응답 및 작업

HTTP 202 · 작업 접수

json
{
  "id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "model": "kling-v3-motion-control",
  "created_at": "2026-07-30T08:00:00Z",
  "status_url": "/v1/videos/tasks/vid_1785398400000000000",
  "content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "status": "queued",
  "updated_at": "2026-07-30T08:00:00Z",
  "task_id": "vid_1785398400000000000"
}

HTTP 200 · 완료 작업 조회

json
{
  "id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "model": "kling-v3-motion-control",
  "created_at": "2026-07-30T08:00:00Z",
  "status_url": "/v1/videos/tasks/vid_1785398400000000000",
  "content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "status": "succeeded",
  "updated_at": "2026-07-30T08:01:00Z",
  "url": "/v1/videos/tasks/vid_1785398400000000000/content"
}

id를 저장하세요. 같은 API 키로 status_url에 GET 요청을 보내 status가 succeeded 또는 failed가 될 때까지 확인하세요. 성공한 뒤 content_url에서 내려받고 HTTP 리디렉션을 따르세요. 두 경로는 API 기본 URL에 대한 상대 경로입니다.

필드유형설명
id / task_idstring작업 ID입니다. 생성 응답의 task_id는 id와 같습니다.
statusstring작업 상태이며 queued, running, succeeded 또는 failed입니다.
progressinteger생성 진행률입니다. 진행률 값이 없으면 생략됩니다.
error.codestring작업 실패 시 반환되는 오류 분류입니다.

주요 오류

HTTP오류 유형설명
400invalid_request모델, 매개변수 조합, 참조 미디어를 확인하세요.
401unauthorizedAPI 키가 누락되었거나 유효하지 않거나 비활성화되었는지 확인하세요.
402insufficient_balance작업 제출에 필요한 잔액이 부족합니다.
404not_found조회 결과가 404이면 작업 ID를 보관하고 조회 URL과 작업을 만든 계정의 API 키를 확인하세요. 작업이 이미 완료되었을 수 있으니 이 응답만으로 다시 제출하지 마세요.
409video_not_ready영상이 아직 생성 중입니다. 상태 조회를 계속하세요.
503submission_unknown제출 결과를 확인할 수 없습니다. 새 요청을 보내기 전에 지원팀에 작업 생성 여부를 확인하세요.

전체 연동 가이드 · 요청 필드, 작업 상태 및 응답 형식은 전체 API 가이드를 참고하세요.

기능 및 제한

  • text_to_video · 미지원
  • reference_images · 지원
  • video_input · 지원
  • 제한 참조 이미지: 최대 1개 · 입력: One image and one video. Modes: std or pro. Reference video: 3–10 seconds for image orientation, 3–30 seconds for video orientation.

모델 기능 카탈로그 · 가격 보기

관련 가이드

동영상 생성 API

텍스트, 시작·끝 프레임 또는 참고 자료로 동영상 작업을 만들고 상태 조회, 결과 다운로드와 완료 작업 삭제까지 진행합니다.

모델 기능 카탈로그

공개 텍스트, 이미지 및 동영상 모델의 정규화된 요청 ID, 호환 프로토콜, 지원 클라이언트, 도구 호출, 미디어 입력·출력 기능, 제한 사항과 검토 날짜를 비교합니다.

가입하고 API Key 받기