본문으로 건너뛰기
API 레퍼런스
API 레퍼런스

Kling 비디오 편집

프롬프트에 따라 원본 영상이나 작업을 수정하고, 선택적으로 참조 이미지를 사용하세요.

Markdown 보기
01

개요

지원되는 모델로 edit video 엔드포인트를 사용하세요. 반환된 Task ID를 사용하여 상태를 조회하거나, 아래에 설명된 전달을 위해 callback_url을 제공하세요.

빠른 시작

  1. API 키를 만들고 RUNAPI_API_KEY로 설정합니다.
  2. 지원되는 모델을 선택하고 해당 모델의 스키마와 일치하는 본문으로 POST 요청을 전송합니다.
  3. 반환된 작업 ID를 저장한 후, 터미널 상태가 될 때까지 폴링하거나 아래에 문서화된 콜백을 처리하세요.

엔드포인트

POST /api/v1/kling/edit_video
Base URL
https://runapi.ai
API 버전
v1
인증
Authorization: Bearer YOUR_API_TOKEN
02

지원 모델

현재 가격, 속도 제한 및 상업적 이용 세부 정보는 모델 페이지를 여십시오.

03

요청 스키마

JSON 본문

필드와 허용 값은 선택된 모델에 따라 다릅니다. 제공된 경우 callback_url은 아래에 문서화된 Task 전달을 수신합니다.

kling-v3-omni-edit필드 10개
aspect_ratiostring
선택

출력 화면 비율; 소스 전용 요청에는 auto가 필요합니다.

허용 값: auto, 16:9, 9:16, 1:1
callback_urlstring
선택

비동기 알림을 위한 웹훅 URL.

duration_secondsinteger
선택

출력 지속 시간(초).

허용 값: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 기본값: 5
enable_soundboolean
선택

동기화된 사운드 생성을 활성화합니다.

기본값: false
modelstring
필수

모델 슬러그.

output_resolutionstring
선택

출력 해상도.

허용 값: 720p, 1080p, 4k 기본값: 720p
promptstring
필수

비디오 설명.

범위: 1 - 2500
reference_image_urlsarray
선택

순서 있는 참조 이미지 URL.

항목 범위: 1 - 4
source_task_idstring
선택

완료된 호환 Task ID. source_video_url과 함께 사용할 수 없습니다.

source_video_urlstring
선택

공개 소스 비디오 URL. source_task_id와 함께 사용할 수 없습니다.

kling-v3-omni-reference필드 10개
aspect_ratiostring
선택

출력 화면 비율; 소스 전용 요청에는 auto가 필요합니다.

허용 값: auto, 16:9, 9:16, 1:1
callback_urlstring
선택

비동기 알림을 위한 웹훅 URL.

duration_secondsinteger
선택

출력 지속 시간(초).

허용 값: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 기본값: 5
enable_soundboolean
선택

동기화된 사운드 생성을 활성화합니다. 소스 비디오 요청에는 false가 필요합니다.

기본값: false
modelstring
필수

모델 슬러그.

output_resolutionstring
선택

출력 해상도.

허용 값: 720p, 1080p, 4k 기본값: 720p
promptstring
필수

비디오 설명.

범위: 1 - 2500
reference_image_urlsarray
선택

순서 있는 참조 이미지 URL.

항목 범위: 1 - 4
source_task_idstring
선택

완료된 호환 Task ID. source_video_url과 함께 사용할 수 없습니다.

source_video_urlstring
선택

공개 소스 비디오 URL. source_task_id와 함께 사용할 수 없습니다.

조건부 규칙

이 요구 사항은 나열된 모든 조건이 일치할 때 적용됩니다.

  1. 다음의 경우 model = kling-v3-omni-edit, source_task_id absent, source_video_url absent
    필수
    허용되지 않음
  2. 다음의 경우 model = kling-v3-omni-edit, source_video_url present
    필수
    허용되지 않음
    source_task_id
  3. 다음의 경우 model = kling-v3-omni-edit, source_task_id present
    필수
    허용되지 않음
    source_video_url
  4. 다음의 경우 model = kling-v3-omni-edit, reference_image_urls absent, source_video_url present
    필수
    aspect_ratio
    허용되지 않음
  5. 다음의 경우 model = kling-v3-omni-edit, reference_image_urls absent, source_task_id present
    필수
    aspect_ratio
    허용되지 않음
  6. 다음의 경우 model = kling-v3-omni-edit, reference_image_urls present, source_video_url present
    필수
    aspect_ratio
    허용되지 않음
  7. 다음의 경우 model = kling-v3-omni-edit, reference_image_urls present, source_task_id present
    필수
    aspect_ratio
    허용되지 않음
  8. 다음의 경우 model = kling-v3-omni-reference, source_task_id absent, source_video_url absent
    필수
    허용되지 않음
  9. 다음의 경우 model = kling-v3-omni-reference, source_video_url present
    필수
    허용되지 않음
    source_task_id
  10. 다음의 경우 model = kling-v3-omni-reference, source_task_id present
    필수
    허용되지 않음
    source_video_url
  11. 다음의 경우 model = kling-v3-omni-reference, reference_image_urls absent, source_video_url present
    필수
    aspect_ratio
    허용되지 않음
  12. 다음의 경우 model = kling-v3-omni-reference, reference_image_urls absent, source_task_id present
    필수
    aspect_ratio
    허용되지 않음
  13. 다음의 경우 model = kling-v3-omni-reference, reference_image_urls present, source_video_url present
    필수
    aspect_ratio
    허용되지 않음
  14. 다음의 경우 model = kling-v3-omni-reference, reference_image_urls present, source_task_id present
    필수
    aspect_ratio
    허용되지 않음
04

수락 만들기

HTTP 202

POST /api/v1/kling/edit_video

응답 스키마
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    },
    "task_replayed": {
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "status"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "id": "tsk_reference_demo",
  "status": "processing"
}
05

폴링 처리 중

HTTP 200

GET /api/v1/kling/edit_video/:id

응답 스키마
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "id": "tsk_reference_demo",
  "status": "processing"
}
06

폴링 완료

HTTP 200

GET /api/v1/kling/edit_video/:id

응답 스키마
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    },
    "usage": {
      "properties": {
        "cost": {
          "type": "number"
        }
      },
      "required": [
        "cost"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "videos": {
      "items": {
        "properties": {
          "url": {
            "type": "string",
            "x-runapi-generated-media": true
          }
        },
        "required": [
          "url"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    }
  },
  "required": [
    "id",
    "status",
    "videos",
    "usage"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "id": "tsk_reference_demo",
  "status": "completed",
  "usage": {
    "cost": 0.05
  },
  "videos": [
    {
      "url": "https://file.runapi.ai/reference-video.mp4"
    }
  ]
}
07

폴링 실패

HTTP 200

GET /api/v1/kling/edit_video/:id

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Task processing failed.",
  "id": "tsk_reference_demo",
  "status": "failed"
}
08

고객 콜백: 완료됨

HTTP 200

POST callback_url

응답 스키마
JSON 
{
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    },
    "usage": {
      "properties": {
        "cost": {
          "type": "number"
        }
      },
      "required": [
        "cost"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "videos": {
      "items": {
        "properties": {
          "url": {
            "type": "string",
            "x-runapi-generated-media": true
          }
        },
        "required": [
          "url"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    }
  },
  "required": [
    "id",
    "status",
    "videos",
    "usage"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "id": "tsk_reference_demo",
  "status": "completed",
  "usage": {
    "cost": 0.05
  },
  "videos": [
    {
      "url": "https://file.runapi.ai/reference-video.mp4"
    }
  ]
}
09

고객 콜백: 실패함

HTTP 200

POST callback_url

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "properties": {
            "code": {
              "type": "string"
            },
            "limit_cents": {
              "type": "integer"
            },
            "message": {
              "type": "string"
            },
            "reset_at": {
              "format": "date-time",
              "type": [
                "string",
                "null"
              ]
            },
            "used_cents": {
              "type": "integer"
            },
            "window": {
              "enum": [
                "1h",
                "1d",
                "7d",
                "daily",
                "weekly",
                "monthly",
                "lifetime"
              ],
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "type": "object",
          "unevaluatedProperties": false
        }
      ]
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": {
    "code": "generation_failed",
    "message": "Task processing failed."
  },
  "id": "tsk_reference_demo",
  "status": "failed"
}
10

오류

HTTP 401

POST /api/v1/kling/edit_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Authentication required"
}
11

오류

HTTP 401

GET /api/v1/kling/edit_video/:id

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Authentication required"
}
12

오류

HTTP 400

POST /api/v1/kling/edit_video

응답 스키마
JSON 
{
  "oneOf": [
    {
      "properties": {
        "error": {
          "description": "사람이 읽을 수 있는 오류 메시지.",
          "type": "string"
        }
      },
      "required": [
        "error"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    {
      "properties": {
        "error": {
          "description": "사람이 읽을 수 있는 유효성 검사 요약입니다.",
          "type": "string"
        },
        "errors": {
          "additionalProperties": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "description": "공개 요청 필드를 키로 하는 유효성 검사 메시지로, 각 필드에 대해 사람이 읽을 수 있는 문자열 배열이 포함됩니다.",
          "type": "object"
        }
      },
      "required": [
        "error",
        "errors"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  ]
}

응답 예시

JSON 
{
  "error": "model must be one of: kling-v3-omni-edit, kling-v3-omni-reference"
}
13

오류

HTTP 402

POST /api/v1/kling/edit_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Insufficient balance"
}
14

오류

HTTP 429

POST /api/v1/kling/edit_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "API key credit limit exceeded"
}
15

오류

HTTP 409

POST /api/v1/kling/edit_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "The request uses features that are not supported for the selected model"
}
16

오류

HTTP 429

POST /api/v1/kling/edit_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Rate limit reached. Please retry later."
}
17

오류

HTTP 503

POST /api/v1/kling/edit_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Service under maintenance, please try again later"
}
18

오류

HTTP 504

POST /api/v1/kling/edit_video

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "The request timed out"
}
19

오류

HTTP 404

GET /api/v1/kling/edit_video/:id

응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Task with id 'tsk_reference_demo' not found"
}
20

생성된 코드 샘플

cURL을 직접 사용하거나 해당 언어의 SDK를 설치하세요. 각 샘플은 이 레퍼런스에 표시된 유효성 검사된 요청을 제출합니다.

설치

Shell 
pip install runapi-kling
PYTHON 
import os
from runapi.kling import KlingClient

client = KlingClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.edit_video.create(
  model="kling-v3-omni-edit",
  prompt="Turn the source into a hand-painted watercolor scene.",
  source_video_url="https://cdn.runapi.ai/public/samples/video.mp4",
  reference_image_urls=["https://cdn.runapi.ai/public/samples/image.jpg"],
  duration_seconds=8,
  output_resolution="1080p",
  enable_sound=True,
  aspect_ratio="16:9"
)