빠른 시작
3D 생성은 비동기 작업이며, 전체 프로세스는 세 단계로 나뉩니다.API 개요
Base URL:
https://aihubmix.com
인증 방식: Bearer Token
비디오 API와 달리, 3D API에는
/content 다운로드 엔드포인트와 DELETE 삭제 엔드포인트가 없습니다. 결과물은 조회 응답의 output[]에 포함된 content_url을 통해 직접 다운로드합니다.지원 모델
생성 유형 (
generate_type)
API 상세 설명
요청 헤더
3D 생성 작업 생성
요청 본문
파라미터 검증 규칙
prompt와input_references는 상호 배타적이며(둘 중 하나만 전달 가능),generate_type: "Sketch"인 경우에만 둘을 동시에 전달할 수 있습니다(스케치 + 텍스트 설명).input_references의 각 항목에서image_url과image_base64는 정확히 하나만 전달해야 합니다:image_url은http(s)공개 URL만 지원하며, data URL은 지원하지 않습니다(image_base64를 사용하세요);image_base64는 디코딩 후 6MB를 초과할 수 없습니다.
hy-3d-3.1은LowPoly생성 유형을 지원하지 않습니다.- 요청 본문 전체 크기는 10MB를 초과할 수 없습니다.
extra_body 사용 안내: 업스트림 네이티브 파라미터(예: polygon_type)는 extra_body 최상위에 넣어 전달할 수 있습니다. 다음 파라미터는 반드시 최상위 필드로 전달해야 하며, extra_body에 포함되면 400이 반환됩니다: model、prompt、image_url、image_base64、generate_type、enable_pbr、face_count、result_format; multi_view_images(멀티뷰 이미지)는 현재 지원하지 않습니다.응답 예시
상태 값 설명
작업 상태 조회
응답 예시 (생성 완료)
output[] 필드 설명
사용 예제
전체 호출 예제
요금 설명
- 건당 과금: 가격은
모델 × generate_type × PBR 사용 여부 × 면 수 지정 여부 × 형식 지정 여부조합에 따라 결정되며, 구체적인 가격은 모델 갤러리를 참조하세요. - 과금은 작업 생성 성공 시점에 발생하며, 작업 상태 조회와 결과물 다운로드는 과금되지 않습니다.
- 가격이 설정되지 않은 파라미터 조합은 생성 시 바로 400이 반환되며, 과금되지 않습니다.
FAQ
3D 생성에는 얼마나 걸리나요?
일반적으로 몇 분이 소요되며, 구체적인 시간은 모델, 생성 유형, 면 수 설정에 따라 다릅니다. 10~15초 간격으로 조회 API를 폴링하는 것을 권장합니다.결과물 링크와 작업의 유효 기간은 얼마나 되나요?
- 작업 ID는 생성 시점부터 24시간 동안 조회할 수 있으며, 응답의
expires_at필드가 조회 마감 시각입니다. content_url/preview_url은 업스트림 임시 링크로 일정 시간이 지나면 만료되므로, 작업 완료 후 가능한 한 빨리 다운로드하여 저장하세요.
prompt와 참조 이미지를 동시에 전달할 수 있나요?
불가능합니다. 둘은 상호 배타적입니다. 유일한 예외는 generate_type: "Sketch"(스케치-3D)로, 스케치 이미지와 텍스트 설명을 동시에 전달할 수 있습니다.
generate_type의 각 유형은 어떤 차이가 있나요?
작업이 실패하면 어떻게 처리하나요?
status가 failed일 때, 응답의 error 필드에 오류 정보가 포함됩니다.
마지막 업데이트: 2026-07-17