> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Luma 비디오 생성 API 연동 설명 > Luma Video Generation 集成指南 - XHuoAPI AI의 적용이 확대됨에 따라, 각종 AI 프로그램이 점차 보편화되고 있습니다. AI는 사람들의 업무와 생활의 모든 측면에 점점 더 깊숙이 들어오고 있습니다. AI가 관련된 산업도 점점 더 많아지고 있으며, 처음에는 글쓰기에서 시작하여 의료 교육, 현재는 비디오에 이르기까지 다양합니다. Luma는 전문 고품질 비디오 생성 플랫폼으로, 사용자는 자료를 업로드하기만 하면 다양한 스타일과 효과에 따라 자동으로 고품질 비디오를 생성할 수 있습니다. 이 AI 비디오 생성기는 유명 기술 회사의 팀원들이 개발하였으며, 복잡한 편집 도구 없이 누구나 쉽게 훌륭한 비디오를 제작할 수 있도록 하는 것을 목표로 하고 있습니다. 하지만 Luma 공식에서는 API를 제공하지 않으며, XHuoAPI는 Luma의 API를 제공하여 Suno 공식과의 연동을 모방하여 원하는 비디오를 편리하고 신속하게 생성할 수 있도록 합니다. ## 신청 및 사용 Luma Videos API를 사용하려면 먼저 [Luma Videos Generation API](https://api.xhuoapi.ai/documents/5bd3597d-1ff8-44ad-a580-b66b48393e7f) 페이지에서 "Acquire" 버튼을 클릭하여 요청에 필요한 자격 증명을 얻을 수 있습니다: ![](https://cdn.xhuoapi.ai/nyq0xz.png) 로그인 또는 등록이 되어 있지 않으면 자동으로 로그인 페이지로 이동하여 등록 및 로그인을 초대합니다. 로그인 및 등록 후에는 자동으로 현재 페이지로 돌아옵니다. 첫 번째 신청 시 무료 한도가 제공되어 해당 API를 무료로 사용할 수 있습니다. ## 기본 사용 어떤 비디오를 생성하고 싶다면, 원하는 텍스트를 입력하면 됩니다. 예를 들어, "우주 비행사가 우주와 화산 사이를 이동하는 비디오"를 생성하고 싶다면 `Astronauts shuttle from space to volcano`를 입력하면 됩니다. 아래와 같이:

생성된 코드는 다음과 같습니다:

주요 요청 매개변수: * `prompt`: 비디오 생성을 위한 프롬프트. * `aspect_ratio`: 비디오의 가로 세로 비율, 기본값 16:9. * `end_image_url`: 선택 사항, 마지막 프레임 지정. * `enhancement`: 선택 사항, 선명도 향상 스위치. * `loop`: 루프 비디오 생성 여부, 기본값 false. * `timeout`: 선택 사항, 타임아웃 초 수. * `callback_url`: 비동기 콜백 주소. "Try" 버튼을 클릭하여 API를 직접 테스트할 수 있으며, 1-2분 정도 기다리면 결과는 다음과 같습니다: ```json theme={null} { "success": true, "task_id": "e4018a99-1522-4f24-9330-62c2a9b50b59", "video_id": "155838f8-7f1e-44d8-b387-192f3b4b509d", "prompt": "Astronauts shuttle from space to volcano", "video_url": "https://storage.cdn-luma.com/dream_machine/af94e7ca-da35-4b5f-a636-2d7254184d0d/watermarked_video0585de3737db946e5a0ac895384ecd180.mp4", "video_height": 752, "video_width": 1360, "state": "completed", "thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/e4018a99-1522-4f24-9330-62c2a9b50b59.jpg", "thumbnail_width": 1360, "thumbnail_height": 752 } ``` 이때 우리는 이 비디오의 관련 정보를 얻을 수 있으며, 여기에는 비디오 ID, 비디오 링크, 비디오 썸네일 등이 포함됩니다. 필드 설명은 다음과 같습니다: * success: 생성 성공 여부, 성공 시 `true`, 실패 시 `false` * task\_id: 이 비디오 생성 작업의 고유 ID * video\_id: 이 비디오 생성 작업에서 생성된 비디오의 고유 ID * prompt: 이 비디오 생성 작업의 키워드 * video\_url: 이 비디오 생성 작업의 결과 비디오 링크 * video\_height: 생성된 비디오 썸네일 이미지의 높이 * video\_width: 생성된 비디오 썸네일 이미지의 너비 * state: 이 비디오 생성 작업의 상태, 작업이 완료되면 `completed`로 표시됩니다. * thumbnail\_url: 생성된 비디오 썸네일 이미지의 링크 * thumbnail\_width: 생성된 비디오 썸네일 이미지의 너비 * thumbnail\_height: 생성된 비디오 썸네일 이미지의 높이 ## 사용자 정의 시작 및 종료 프레임 생성 비디오의 시작 및 종료 프레임을 사용자 정의하여 비디오를 생성하고 싶다면, 시작 및 종료 프레임의 이미지 링크를 입력할 수 있습니다: 이때 비디오의 시작 프레임 `start_image_url` 필드에는 다음 이미지를 비디오의 시작 프레임으로 사용할 수 있습니다: ![시작 프레임](https://cdn.xhuoapi.ai/r9vsv9.png) 그 다음, 시작 및 종료 프레임, 키워드를 기반으로 비디오를 사용자 정의하여 생성할 수 있으며, 다음과 같은 내용을 지정할 수 있습니다: * action: 비디오 생성 작업의 행동, 일반 생성 `generate`와 확장 생성 `extend`가 있으며, 기본값은 `generate`입니다. * start\_image\_url: 생성할 비디오의 시작 프레임을 지정합니다. * end\_image\_url: 생성할 비디오의 종료 프레임을 지정합니다. * prompt: 비디오 생성을 위한 키워드 내용. 입력 예시는 다음과 같습니다:

입력이 완료되면 자동으로 생성된 코드는 다음과 같습니다:

해당 코드: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/luma/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "start_image_url": "https://cdn.xhuoapi.ai/r9vsv9.png", "action": "generate", "prompt": "Astronauts shuttle from space to volcano" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` 얻은 결과는 다음과 같습니다: ```json theme={null} { "success": true, "task_id": "12a18694-fd4b-47e7-9c50-34f30862cff6", "video_id": "0105c090-03a5-425a-8026-523341cd575b", "prompt": "Astronauts shuttle from space to volcano", "video_url": "https://platform.cdn.xhuoapi.ai/luma/12a18694-fd4b-47e7-9c50-34f30862cff6.mp4", "video_height": 656, "video_width": 1552, "state": "completed", "thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/12a18694-fd4b-47e7-9c50-34f30862cff6.jpg", "thumbnail_width": 1552, "thumbnail_height": 656 } ``` 마지막으로 얻은 결과는 위의 내용과 유사하며, 생성된 비디오의 시작 프레임에는 우리가 전달한 이미지가 포함되어 있습니다. 물론 시작 및 종료 프레임 이미지 링크를 동시에 전달하여 비디오를 생성할 수도 있으며, 위의 내용에 종료 프레임 이미지를 추가하기만 하면 됩니다. 종료 프레임의 이미지 정보는 다음과 같습니다: ![종료 프레임](https://cdn.xhuoapi.ai/0iad3k.png) 입력 예시는 다음과 같습니다:

마지막으로 다음과 같은 결과를 얻습니다: ```json theme={null} { "success": true, "task_id": "d1cb723a-e554-4775-94a4-bb6ae8c7ea67", "video_id": "6bebd0d2-f793-472e-9326-38528a9273bb", "prompt": "우주에서 화산으로 이동하는 우주비행사", "video_url": "https://platform.cdn.xhuoapi.ai/luma/d1cb723a-e554-4775-94a4-bb6ae8c7ea67.mp4", "video_height": 656, "video_width": 1552, "state": "완료", "thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/d1cb723a-e554-4775-94a4-bb6ae8c7ea67.jpg", "thumbnail_width": 1552, "thumbnail_height": 656 } ``` 결과는 위와 유사하며, 생성된 비디오는 첫 프레임과 마지막 프레임의 이미지를 모두 포함하고 있어, 사용자 정의 첫 및 마지막 프레임을 통해 비디오를 생성하는 것이 완료되었습니다. ## 비디오 확장 기능 생성된 비디오를 계속 생성하고 싶다면, 매개변수 `action`을 `extend`로 설정하고, 계속 생성할 비디오의 ID 또는 비디오 링크를 입력해야 합니다. 비디오 ID와 비디오 링크는 기본 사용에 따라 얻을 수 있으며, 아래 그림과 같이 표시됩니다:

이때 비디오 ID는 다음과 같습니다: ``` "video_id": "0105c090-03a5-425a-8026-523341cd575b", "video_url": "https://platform.cdn.xhuoapi.ai/luma/12a18694-fd4b-47e7-9c50-34f30862cff6.mp4" ``` > 주의: 여기서 비디오의 `video_id`와 `video_url`은 생성된 비디오의 ID와 비디오 링크입니다. 비디오 생성 방법을 모르신다면, 위의 기본 사용을 참조하여 비디오를 생성할 수 있습니다. 비디오를 계속 생성하려면 비디오 링크 또는 비디오 ID를 업로드해야 하며, 아래에서는 비디오 ID를 사용하여 확장하는 방법을 시연합니다. 다음으로 키워드를 입력하여 비디오를 사용자 정의 생성해야 하며, 다음과 같은 내용을 지정할 수 있습니다: * action: 이때 비디오를 확장하는 행동으로, 여기서는 `extend`입니다. * prompt: 비디오를 확장할 키워드입니다. * video\_url: 확장할 비디오의 링크입니다. * video\_id: 확장할 비디오의 고유 ID입니다. * end\_image\_url: 확장 생성 비디오에 지정할 마지막 프레임의 이미지 링크, 선택적 매개변수입니다. 입력 예시는 다음과 같습니다:

입력이 완료되면 자동으로 생성된 코드는 다음과 같습니다:

해당 Python 코드: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/luma/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "action": "extend", "video_id": "0105c090-03a5-425a-8026-523341cd575b", "prompt": "우주에서 화산으로 이동하는 우주비행사" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` 실행을 클릭하면 다음과 같은 결과를 얻을 수 있습니다: ```json theme={null} { "success": true, "task_id": "c6e529d1-a06d-4c12-91b2-c855135131c3", "video_id": "36908c49-c2bb-4a11-bd5a-b8512b004818", "prompt": "우주에서 화산으로 이동하는 우주비행사", "video_url": "https://platform.cdn.xhuoapi.ai/luma/c6e529d1-a06d-4c12-91b2-c855135131c3.mp4", "video_height": 656, "video_width": 1552, "state": "완료", "thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/c6e529d1-a06d-4c12-91b2-c855135131c3.jpg", "thumbnail_width": 1552, "thumbnail_height": 656 } ``` 해당 비디오는 확장할 비디오를 기반으로 확장된 것으로, 결과 내용은 위와 일치하며, 이는 노래의 계속 생성 기능을 구현한 것입니다. 물론 비디오 링크를 지정하여 확장 생성할 수도 있으며, 다음 정보를 입력합니다:

실행 후 다음과 같은 결과를 얻었습니다: ```json theme={null} { "success": true, "task_id": "1dcb5902-a7be-4b77-ba5d-dd8ec82b26ca", "video_id": "f0187dc2-339f-4a08-a435-c3a3341f620a", "prompt": "우주에서 화산으로 이동하는 우주비행사", "video_url": "https://platform.cdn.xhuoapi.ai/luma/1dcb5902-a7be-4b77-ba5d-dd8ec82b26ca.mp4", "video_height": 656, "video_width": 1552, "state": "완료", "thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/1dcb5902-a7be-4b77-ba5d-dd8ec82b26ca.jpg", "thumbnail_width": 1552, "thumbnail_height": 656 } ``` 결과에 따르면 비디오 링크를 통해서도 비디오 확장 기능을 구현할 수 있습니다. 마지막으로 확장 비디오에서 특정 마지막 프레임 이미지를 지정하여 확장할 수 있으며, 아래는 마지막 프레임 이미지 정보입니다: ![마지막 프레임](https://cdn.xhuoapi.ai/0iad3k.png) 다음으로 위의 내용을 바탕으로 마지막 프레임 이미지 정보를 추가합니다. 구체적인 내용은 다음과 같습니다:

실행을 클릭하면 다음과 같은 정보를 얻습니다: ```json theme={null} { "success": true, "task_id": "b816b2b4-c345-4673-9e19-83e91f91b643", "video_id": "c5400053-63e6-4206-8082-31cf9dd1e7ed", "prompt": "우주에서 화산으로 이동하는 우주비행사", "video_url": "https://platform.cdn.xhuoapi.ai/luma/b816b2b4-c345-4673-9e19-83e91f91b643.mp4", "video_height": 656, "video_width": 1552, "state": "완료", "thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/b816b2b4-c345-4673-9e19-83e91f91b643.jpg", "thumbnail_width": 1552, "thumbnail_height": 656 } ``` 확인해보면, 위의 확장 비디오를 기반으로 마지막 프레임 이미지를 지정하여 확장할 수 있습니다. ## 비동기 콜백 Luma가 비디오를 생성하는 데 시간이 상대적으로 길어 약 1-2분이 소요되므로, API가 오랜 시간 응답하지 않으면 HTTP 요청이 연결을 유지하여 추가 시스템 자원 소모를 초래할 수 있습니다. 따라서 이 API는 비동기 콜백 지원도 제공합니다. 전체 프로세스는 다음과 같습니다: 클라이언트가 요청을 시작할 때, 추가로 `callback_url` 필드를 지정합니다. 클라이언트가 API 요청을 시작한 후, API는 즉시 결과를 반환하며, 현재 작업 ID를 나타내는 `task_id` 필드 정보를 포함합니다. 작업이 완료되면, 생성된 음악 결과가 POST JSON 형식으로 클라이언트가 지정한 `callback_url`로 전송되며, 여기에도 `task_id` 필드가 포함되어 있어 작업 결과를 ID로 연결할 수 있습니다. 아래 예제를 통해 구체적으로 어떻게 작업하는지 알아보겠습니다. 먼저, Webhook 콜백은 HTTP 요청을 수신할 수 있는 서비스로, 개발자는 자신이 구축한 HTTP 서버의 URL로 교체해야 합니다. 여기서는 편리한 시연을 위해 공개 Webhook 샘플 사이트인 [https://webhook.site/를](https://webhook.site/를) 사용합니다. 해당 사이트를 열면 Webhook URL을 얻을 수 있습니다. 아래 그림과 같이 표시됩니다:

이 URL을 복사하면 Webhook으로 사용할 수 있으며, 여기서의 샘플은 [https://webhook.site/0c87ca0e-cd74-4577-8d68-f2b80fbf8a13입니다](https://webhook.site/0c87ca0e-cd74-4577-8d68-f2b80fbf8a13입니다). 다음으로, `callback_url` 필드를 위의 Webhook URL로 설정하고, `prompt`를 입력할 수 있습니다. 아래 그림과 같이 표시됩니다:

실행 버튼을 클릭하면 즉시 결과를 얻을 수 있습니다. 결과는 다음과 같습니다: ```json theme={null} { "task_id": "732f8282-7cf8-401c-95f2-42c33aa079a6" } ``` 잠시 기다리면, [https://webhook.site/0c87ca0e-cd74-4577-8d68-f2b80fbf8a13에서](https://webhook.site/0c87ca0e-cd74-4577-8d68-f2b80fbf8a13에서) 생성된 곡의 결과를 확인할 수 있습니다. 아래 그림과 같이 표시됩니다: ![](https://cdn.xhuoapi.ai/1hwm5m.png) 내용은 다음과 같습니다: ```json theme={null} { "success": true, "task_id": "732f8282-7cf8-401c-95f2-42c33aa079a6", "video_id": "4d8013c3-5de0-41aa-966e-0b1a51d1c633", "prompt": "Astronauts shuttle from space to volcano", "video_url": "https://platform.cdn.xhuoapi.ai/luma/732f8282-7cf8-401c-95f2-42c33aa079a6.mp4", "video_height": 752, "video_width": 1360, "state": "completed", "thumbnail_url": "https://platform.cdn.xhuoapi.ai/luma/732f8282-7cf8-401c-95f2-42c33aa079a6.jpg", "thumbnail_width": 1360, "thumbnail_height": 752 } ``` 결과에서 `task_id` 필드가 있으며, 다른 필드들은 위와 유사합니다. 이 필드를 통해 작업의 연관성을 실현할 수 있습니다.