이 페이지
Hailuo 2.3 API
하나의 비동기 API로 Hailuo 2.3 텍스트·이미지 기반 동영상 작업을 만듭니다. 더 낮은 지연 시간의 이미지 생성에는 Hailuo 2.3 Fast를 사용할 수 있습니다.
REST API · v1 · 비동기 작업
첫 요청 보내기
고유한 멱등 키로 작업을 만들고 task ID를 저장한 다음 결과가 준비될 때까지 조회합니다.
- 1
API Key 생성
Imya 계정 설정에서 키를 발급합니다.
- 2
작업 생성
Hailuo 2.3 또는 Fast를 선택하고 입력을 보냅니다.
- 3
결과 조회
성공하거나 실패할 때까지 task ID를 조회합니다.
인증과 멱등성
API Key를 Bearer 토큰으로 보내고 모든 생성 POST에 고유한 Idempotency-Key를 사용해 안전한 재시도의 중복 과금을 막습니다.
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY동영상 생성 작업 만들기
비동기 Hailuo 작업을 만들고 이 요청에 대해 계산한 실시간 credits_reserved를 반환합니다.
/v1/videos/generations# Text to video (Hailuo 2.3)
curl https://imya.ai/v1/videos/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: hailuo-t2v-order-001" \
-d '{
"model": "hailuo-2.3",
"prompt": "A paper boat crossing a rain-soaked neon street",
"duration": 6,
"resolution": "720p",
"prompt_optimizer": true
}'
# Image to video (Hailuo 2.3 Fast)
curl https://imya.ai/v1/videos/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: hailuo-i2v-order-001" \
-d '{
"model": "hailuo-2.3-fast",
"prompt": "Slow camera push-in with warm moving light",
"image_url": "https://cdn.example.com/first-frame.jpg",
"duration": 6,
"resolution": "1080p"
}'기존 Beta 호환
기존 연동은 POST /api/video/generate와 x-api-key를 계속 사용할 수 있지만 POST에 Idempotency-Key도 필요합니다. 새 연동은 /v1/videos/generations를 사용하세요.
curl https://imya.ai/api/video/generate \
-H "x-api-key: YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: legacy-hailuo-order-001" \
-d '{
"modelKey": "hailuo-2-3-standard-t2v",
"prompt": "A paper boat crossing a rain-soaked neon street",
"resolution": "720p",
"outputDurationSec": 6,
"promptExtend": true
}'작업 조회
최신 상태, 최종 크레딧, MP4 또는 안전한 오류를 반환합니다. 5초 이상 간격으로 조회하고 임시 동영상 URL은 즉시 다운로드하세요.
/v1/tasks/{id}curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"요청 파라미터
| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
| model | string | 예 | hailuo-2.3 또는 hailuo-2.3-fast. |
| prompt | string | 예 | 최대 5,000자의 생성 지시. |
| image_url | string | 조건부 | 공개 HTTPS 첫 프레임. Fast에는 필수이며 표준 텍스트 생성에서는 생략합니다. |
| duration | number | 아니요 | 6초 또는 10초. 기본값 6. |
| resolution | string | 아니요 | 720p 또는 1080p. 1080p는 6초만 지원합니다. |
| prompt_optimizer | boolean | 아니요 | 프롬프트 최적화. 기본값 true. |
응답
{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "pending",
"model": "hailuo-2.3",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:00.000Z",
"credits_reserved": 225
}{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "succeeded",
"model": "hailuo-2.3",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:02:18.000Z",
"credits_reserved": 225,
"credits_used": 225,
"data": [
{
"url": "https://media.example.com/generated/example.mp4"
}
]
}실시간 크레딧 과금
서버가 모델, 워크플로, 해상도, 길이와 플랜에서 credits_reserved를 계산합니다. 예제 숫자는 형식 설명용이며 항상 실제 응답 값을 사용하세요.
작업 상태
pending작업이 접수되어 시작을 기다립니다.
processing모델이 동영상을 생성 중입니다.
succeeded생성이 끝났고 data에 MP4가 있습니다.
failed생성에 실패했습니다. 안전한 error를 확인하세요.
오류
400Idempotency-Key가 없거나 JSON이 잘못되었습니다.
401API Key가 없거나 유효하지 않습니다.
402크레딧이 부족합니다.
403API 계정이 비활성화되었습니다.
404작업이 없거나 다른 계정 소유입니다.
409멱등 키를 다른 본문에 재사용했습니다.
413요청 본문이 64 KiB를 초과합니다.
415Content-Type은 application/json이어야 합니다.
422모델, 프롬프트, 이미지, 길이 또는 해상도가 유효하지 않습니다.
429속도 또는 동시 작업 한도에 도달했습니다.
5xx요청을 완료하거나 제출하지 못했습니다.
Imya 공개 API 공통 계약
다음 규칙은 모든 공개 이미지·동영상 생성 엔드포인트에 적용됩니다. 모델별 필드와 요금은 위 파라미터 표를 따릅니다.
과금과 안전한 재시도
새 작업이 접수될 때 credits_reserved의 정확한 크레딧을 원자적으로 차감합니다. 같은 Idempotency-Key와 본문을 재전송하면 중복 과금 없이 원래 작업을 반환합니다.
시간 초과와 환불
30분 안에 종료되지 않은 작업은 실패합니다. 대상 크레딧은 원래 만료일을 유지하며 한 번만 환불됩니다.
속도와 동시 실행 제한
API Key당 60초에 120회 요청, 계정당 이미지 5개 또는 동영상 3개의 동시 작업 한도를 적용합니다. 429의 Retry-After를 따르세요.
조회와 소유권
생성 응답의 id로 GET /v1/tasks/{id}를 5초 이상 간격으로 조회합니다. 생성한 계정만 작업을 읽을 수 있으며 webhook, SDK, batch 제출은 제공하지 않습니다.
오류와 콘텐츠 안전
공개 오류는 업스트림 자격 증명, 내부 URL과 인프라 정보를 제거합니다. 안전하지 않은 프롬프트는 prompt_blocked로 거부될 수 있습니다.
이미지 결과 보관
무료 계정은 7일, 활성 유료 또는 Lifetime 계정은 최대 30일 보관합니다. 삭제 후 status는 failed이고 error.code는 media_deleted입니다.
Hailuo 2.3 API 프로덕션 연동 가이드
Hailuo 2.3 연동을 긴 HTTP 요청이 아니라 복구 가능한 비동기 작업 시스템으로 설계하세요. Imya가 반환한 id를 저장하고 재시도를 결정적으로 처리합니다.
모델 계약에서 파라미터 선택
제출 전에 이 페이지의 파라미터 표로 요청을 검증하세요. 최소 지원 설정부터 시작하고 제품에 필요할 때만 품질, 크기, 길이 또는 참조 수를 늘립니다.
문서화된 길이, 해상도, 비율, 오디오와 입력 미디어 조합만 허용하세요.
복구 가능한 비동기 흐름 설계
동영상 작업을 제출하고 id를 저장한 뒤 백그라운드 워커에서 GET /v1/tasks/{id}를 5초 이상 간격으로 조회합니다. 공개 status는 pending, processing, succeeded, failed이며 30분의 하드 마감에 도달하면 중지합니다. webhook, SDK, batch 제출은 현재 제공하지 않습니다.
- 01UI 업데이트 전에 id, status, credits_reserved와 요청 식별자를 저장합니다.
- 02일시적 오류에는 백오프하고 429의 Retry-After를 준수하며 전송 오류를 새 유료 작업으로 자동 변환하지 않습니다.
- 03계정당 동시에 최대 3개의 동영상 작업과 API Key당 60초에 120회 요청을 허용합니다.
과금과 재시도를 결정적으로 처리
새 작업 접수 시 credits_reserved가 원자적으로 차감됩니다. 의도한 생성마다 Idempotency-Key를 저장하고 같은 본문으로 재사용하면 중복 과금 없이 원래 작업이 반환됩니다.
대상 실패 작업은 원래 만료일을 유지해 한 번만 환불됩니다. 처리 중에는 error.code가 refund_pending이고 완료 후 credits_refunded가 표시됩니다.
자격 증명, 소유권과 미디어 보호
API Key를 서버에 보관하고 id를 인증된 사용자 또는 워크스페이스에 연결하세요. 지원용 요청·작업 ID만 기록하고 프롬프트, 비공개 URL과 자격 증명을 노출하지 마세요.
고정 동영상 보관 기간을 가정하지 마세요. 성공 후 필요한 결과를 동의와 개인정보 처리방침에 따라 즉시 자체 저장소로 복사하세요.
프로덕션 체크리스트
- 제출 전에 모델별 필드를 검증합니다.
- 작업마다 Idempotency-Key와 본문을 저장합니다.
- 상태를 저장하고 5초 이상 간격으로 조회합니다.
- 계정 동시 실행과 Key 속도 제한을 적용합니다.
- 네 status와 media_deleted, refund_pending, credits_refunded를 처리합니다.
- 자격 증명을 서버에 두고 보관 정책을 정의합니다.
자주 묻는 질문
얼마나 자주 조회해야 하나요?
최소 5초를 기다리고 처리 중에는 더 느린 백오프를 사용하세요.
크레딧은 언제 차감되나요?
새 작업 접수 시 정확한 credits_reserved가 원자적으로 차감됩니다.
재시도가 중복 과금되나요?
같은 Idempotency-Key와 본문이면 원래 작업을 반환합니다.
최종 실패는 어떻게 처리하나요?
안전한 오류를 표시하고 id를 보관하며 credits_refunded로 서버 환불 완료를 확인하세요.
연동 전에 Hailuo를 시험할까요?
온라인 Hailuo 2.3 도구에서 Fast·표준과 텍스트·이미지 입력을 비교하세요.
Hailuo 2.3 온라인 사용