튜토리얼

Ray 3.2 API는 어떻게 사용하나요? 5분 만에 첫 영상 만들기

온라인 체험 4단계, API 연동 4단계, 바로 실행 가능한 curl과 Python, 첫 프레임·마지막 프레임 작성법과 출시 전 주의사항까지.

Oct 21, 2026

모델: ray-3.2

TL;DR

무엇인가: Luma AI의 Ray 3.2는 HiAPI에서 두 가지 경로로 제공됩니다. ray-3.2/text-to-video는 프롬프트만 받고, ray-3.2/image-to-video는 첫 프레임(선택적으로 마지막 프레임)으로 구동됩니다. 이미 HiAPI에 출시되어 텍스트→비디오 모델 페이지 열기에서 바로 생성할 수 있으며, 신규 가입 시 200 크레딧을 드립니다.
가격: 편당 과금, 5초 540p $0.2145, 720p $0.429, 1080p $1.7145. 10초는 텍스트→비디오에만 있으며 540p $0.643, 720p $1.286, 1080p $5.143. 실패 시 자동 환불됩니다.
API 호출 방법: POST https://api.hiapi.ai/v1/tasks, model에 해당 경로를 입력하고 taskId를 받은 뒤 폴링하거나 callback.url을 기다린 후, data.output[0].url에서 무음 MP4를 다운로드하세요.

Ray 3.2의 출력은 무음 MP4입니다. 텍스트→비디오는 요청에서 길이와 화면 비율을 선택할 수 있고, 이미지→비디오는 5초 고정이며 화면 비율은 첫 프레임을 따릅니다. 아래에서 온라인 체험부터 curl, Python, 이미지→비디오, 출시 전 주의사항까지 한 번에 살펴봅니다.

Ray 3.2는 무엇인가? 두 경로 선택법

텍스트→비디오: prompt만 전송하고, 선택적으로 duration(5 또는 10초), resolution(540p / 720p / 1080p), aspect_ratio(16:9, 9:16, 1:1, 4:3, 3:4, 21:9)를 지정합니다. 프롬프트는 최대 6000자입니다.
이미지→비디오: prompt와 첫 프레임 image_url이 필수이며, 선택적으로 마지막 프레임 end_image_url, resolution을 지정합니다. 편당 5초 고정이고 화면 비율은 첫 프레임을 따르며 가장 가까운 지원 비율로 자동 매칭됩니다.
공통점: 둘 다 /v1/tasks를 사용하고, 편당 과금이며, 오디오 트랙이 없는 MP4를 출력합니다.

텍스트→비디오는 텍스트 구상만 있고 10초 또는 지정 화면 비율이 필요한 장면에 적합하고, 이미지→비디오는 제품 이미지, 포스터, 콘셉트 아트가 있거나 마지막 화면을 고정하고 싶을 때 적합합니다. 두 경로가 공유하는 5초 세 가지 화질은 동일 가격이며, 10초는 텍스트→비디오에만 있습니다.

Slow cinematic dolly-in toward a lone lighthouse keeper standing on a weathered iron balcony, salt spray drifting across the frame. Overcast dawn light, cool blue-grey tones, soft diffused shadows. The camera glides forward at a steady, patient pace, compressing the distance as gulls cross the background. Anamorphic lens look, shallow depth of field, gentle film grain. Negative: no text, no logos, no warping hands, no abrupt cuts.

이 프롬프트로 생성하기 →, 화면 비율 21:9 선택, 540p 한 편 $0.2145.

두 가지 시작 경로: 온라인 체험 vs API?

온라인 체험(약 1분)

Ray 3.2 텍스트→비디오 모델 페이지를 열거나 위의 미리 채워진 링크를 클릭하세요.
가입 또는 로그인하면 신규 계정에 200 크레딧이 제공됩니다. 5초 540p 한 편에 429 크레딧이 차감되므로 충전 후 생성할 수 있습니다.
프롬프트를 작성하고 길이, 해상도, 화면 비율을 선택한 뒤 실행을 클릭하세요.
결과물이 만족스러우면 다운로드하세요. API가 필요하면 콘솔에서 Key를 생성하세요.

API 연동(약 5분)

HiAPI 콘솔에서 API Key(sk-...)를 생성합니다.
POST /v1/tasks로 작업을 생성하고 응답에서 data.taskId를 받습니다.
GET /v1/tasks/{id}로 조회하거나, 요청 본문 최상위에 callback.url을 포함해 알림을 기다립니다.
data.status가 success가 되면 data.output[0].url에서 영상을 다운로드합니다.

5초 540p 한 편 $0.2145, $10으로 약 46편을 생성할 수 있어 한 세트의 장면 동작을 충분히 테스트할 수 있습니다. 모델 페이지에서 첫 편 시도하기 →

첫 영상: curl 버전

텍스트→비디오 작업 생성:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ray-3.2/text-to-video",
    "input": {
      "prompt": "Slow cinematic dolly-in toward a lone lighthouse keeper standing on a weathered iron balcony, salt spray drifting across the frame. Overcast dawn light, cool blue-grey tones, soft diffused shadows. The camera glides forward at a steady, patient pace, compressing the distance as gulls cross the background. Anamorphic lens look, shallow depth of field, gentle film grain. Negative: no text, no logos, no warping hands, no abrupt cuts.",
      "duration": 5,
      "resolution": "540p",
      "aspect_ratio": "21:9"
    }
  }'

반환된 작업 ID는 data.taskId에 있습니다:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

결과 조회:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

필수는 prompt뿐입니다. duration 기본값 5, resolution 기본값 540p, aspect_ratio 기본값 16:9. 세 필드 모두 엄격하게 검증하며 잘못된 값을 전달하면 바로 400이 반환되고 자동 반올림되지 않습니다.

첫 영상: Python 버전

생성, 폴링, 다운로드를 한 번에 작성:

import time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "ray-3.2/text-to-video",
    "input": {
        "prompt": "Slow cinematic dolly-in toward a lone lighthouse keeper standing on a weathered iron balcony, salt spray drifting across the frame. Overcast dawn light, cool blue-grey tones, soft diffused shadows. The camera glides forward at a steady, patient pace, compressing the distance as gulls cross the background. Anamorphic lens look, shallow depth of field, gentle film grain. Negative: no text, no logos, no warping hands, no abrupt cuts.",
        "duration": 5,
        "resolution": "540p",
        "aspect_ratio": "21:9",
    },
}

resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
task_id = resp.json()["data"]["taskId"]

while True:
    task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if task["status"] in ("success", "fail"):
        break
    time.sleep(5)

if task["status"] == "success":
    video_url = task["output"][0]["url"]
    with open("ray32-clip.mp4", "wb") as f:
        f.write(requests.get(video_url, timeout=120).content)
else:
    print(task.get("error"))

영상 작업은 보통 수십 초에서 수 분이 걸리므로 폴링 간격은 5초로, 타임아웃 상한은 10~15분으로 두세요. 출력 링크는 만료되므로 받은 즉시 다운로드해 자체 스토리지에 저장하세요.

이미지→비디오: 첫 프레임 추가, 또는 첫·마지막 프레임

model을 ray-3.2/image-to-video로 바꾸고 첫 프레임 image_url을 추가하면 같은 요청이 이미지→비디오가 됩니다:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ray-3.2/image-to-video",
    "input": {
      "prompt": "The ribbon of milk keeps folding down through the iced espresso, the ice cubes settle and shift slightly, condensation beads slide down the outside of the glass, very slow push-in toward the glass, warm rim light stays steady, vertical product commercial shot",
      "image_url": "https://www.hiapi.ai/images/model-pages/ray-3-2/iced-coffee-first.jpg",
      "resolution": "1080p"
    }
  }'

마지막 화면을 고정하려면 end_image_url을 추가하세요. 첫 프레임과 마지막 프레임의 카메라 위치, 조명, 피사체 위치가 가까울수록 전환이 안정적입니다. 두 이미지의 구도가 다르면 모델이 자체적으로 카메라 이동을 추가해 연결합니다. 두 필드 모두 가격에 영향을 주지 않습니다.

이미지→비디오에는 duration과 aspect_ratio가 없습니다. 편당 5초 고정이고 화면 비율은 첫 프레임을 기준으로 16:9, 9:16, 1:1, 4:3, 3:4, 21:9 중 가장 가까운 비율로 매칭되며, 비율이 일치하지 않으면 가장자리가 잘립니다. 출력 비율을 완전히 제어하려면 첫 프레임을 이 여섯 가지 비율 중 하나로 먼저 잘라두세요.

출시 전 주의할 3가지

서버에서는 콜백을 사용하세요. 요청 본문 최상위에 "callback": {"url": "https://yourapp.com/webhook", "when": "final"}를 추가하면 작업이 종료 상태에 들어갈 때 자동으로 알림이 와서 폴링을 생략할 수 있습니다. success와 fail 모두 콜백되므로 서버에서는 taskId로 멱등 처리를 하세요.
타임아웃 시 POST를 반복하지 마세요. POST할 때마다 새 작업이 생성되고 개별 과금됩니다. 먼저 taskId를 저장하고 재시도 전에 자체 시스템에서 중복을 제거하세요. 프로세스가 중단되면 저장한 id로 조회를 이어가세요.
모든 요청에 파라미터를 명시하세요. resolution이 단가를 직접 결정하고, duration은 정수 5 또는 10만 받으며, 이미지→비디오에는 duration과 aspect_ratio를 넣지 마세요. 요청에 고정해 두어야 청구와 동작을 예측할 수 있습니다.

자주 나는 오류, 한 줄씩

400 INVALID_REQUEST, resolution 값이 잘못됨 → 540p, 720p, 1080p만 허용되며 2k, 480p는 없습니다.
400, duration 값이 잘못됨 → 정수 5와 10만 허용됩니다. 문자열 "5"나 숫자 7은 실패합니다.
400 additional properties 'aspect_ratio' not allowed → 이미지→비디오에는 이 필드가 없으니 삭제하세요. 텍스트→비디오만 지원합니다.
401 permission_denied → Key가 없거나 잘못되었거나 폐기되었습니다. Authorization: Bearer sk-...를 확인하세요.
생성 시 200 반환 후 작업이 나중에 fail → 보통 이미지→비디오의 image_url이 열리지 않거나 이미지가 아닌 경우입니다. 생성 시에는 필드 형식만 검증하고 URL 접근 가능 여부는 검증하지 않습니다.
며칠 후 링크가 열리지 않음 → 출력 URL은 유효 기간이 있으므로 받은 즉시 다운로드하세요.

실패한 작업의 사전 차감 금액은 자동으로 전액 환불됩니다.

자주 묻는 질문

Ray 3.2 영상 한 편의 길이는? 텍스트→비디오는 5초 또는 10초 선택 가능, 이미지→비디오는 5초 고정입니다.

프롬프트는 얼마나 길게 쓸 수 있나요? 두 경로 모두 1~6000자입니다.

결과물에 소리가 있나요? 없습니다. 출력은 오디오 트랙이 없는 MP4이며 배경음악과 효과음은 후반 작업에서 추가합니다.

이미지→비디오에서 화면 비율을 직접 선택할 수 있나요? 아니요. 화면 비율은 첫 프레임을 따르며 가장 가까운 지원 비율로 자동 매칭됩니다.

텍스트→비디오에 참조 이미지를 전달할 수 있나요? 아니요. 이미지로 구동하려면 ray-3.2/image-to-video를 사용하세요.

Ray 3.2 시리즈 글

지금 시도하세요: 위 등대 영상 아래의 이 프롬프트로 생성하기 →를 클릭하세요. 프롬프트가 이미 채워져 있으니 5초, 540p, 21:9를 선택하고 한 번 누르면 같은 결과물이 나옵니다.

태그API 연동 튜토리얼

모든 아티클 보기 →