메인 콘텐츠로 건너뛰기

빠른 시작

3D 생성은 비동기 작업이며, 전체 프로세스는 세 단계로 나뉩니다.
최소 예제

API 개요

Base URL: https://aihubmix.com 인증 방식: Bearer Token
비디오 API와 달리, 3D API에는 /content 다운로드 엔드포인트와 DELETE 삭제 엔드포인트가 없습니다. 결과물은 조회 응답의 output[]에 포함된 content_url을 통해 직접 다운로드합니다.

지원 모델

생성 유형 (generate_type)

API 상세 설명

요청 헤더

3D 생성 작업 생성

요청 본문

파라미터 검증 규칙
  • promptinput_references상호 배타적이며(둘 중 하나만 전달 가능), generate_type: "Sketch"인 경우에만 둘을 동시에 전달할 수 있습니다(스케치 + 텍스트 설명).
  • input_references의 각 항목에서 image_urlimage_base64정확히 하나만 전달해야 합니다:
    • image_urlhttp(s) 공개 URL만 지원하며, data URL은 지원하지 않습니다(image_base64를 사용하세요);
    • image_base64는 디코딩 후 6MB를 초과할 수 없습니다.
  • hy-3d-3.1LowPoly 생성 유형을 지원하지 않습니다.
  • 요청 본문 전체 크기는 10MB를 초과할 수 없습니다.
extra_body 사용 안내: 업스트림 네이티브 파라미터(예: polygon_type)는 extra_body 최상위에 넣어 전달할 수 있습니다. 다음 파라미터는 반드시 최상위 필드로 전달해야 하며, extra_body에 포함되면 400이 반환됩니다: modelpromptimage_urlimage_base64generate_typeenable_pbrface_countresult_format; multi_view_images(멀티뷰 이미지)는 현재 지원하지 않습니다.

응답 예시

상태 값 설명

작업 상태 조회

이 API를 폴링하여 작업 완료 여부를 확인합니다. 10~15초마다 한 번씩 조회하는 것을 권장합니다. 조회는 과금되지 않습니다.

응답 예시 (생성 완료)

output[] 필드 설명
content_urlpreview_url임시 링크로 일정 시간이 지나면 만료되므로, 작업 완료 후 가능한 한 빨리 다운로드하여 자체 스토리지에 저장하세요. 작업 ID는 생성 시점부터 24시간 동안 조회할 수 있으며(expires_at 필드가 조회 마감 시각), 만료 후 조회하면 오류가 반환됩니다. 임시 링크는 GET 요청만 지원하며, HEAD 요청은 403을 반환합니다.

사용 예제

전체 호출 예제

요금 설명

  • 건당 과금: 가격은 모델 × generate_type × PBR 사용 여부 × 면 수 지정 여부 × 형식 지정 여부 조합에 따라 결정되며, 구체적인 가격은 모델 갤러리를 참조하세요.
  • 과금은 작업 생성 성공 시점에 발생하며, 작업 상태 조회와 결과물 다운로드는 과금되지 않습니다.
  • 가격이 설정되지 않은 파라미터 조합은 생성 시 바로 400이 반환되며, 과금되지 않습니다.

FAQ

3D 생성에는 얼마나 걸리나요?

일반적으로 몇 분이 소요되며, 구체적인 시간은 모델, 생성 유형, 면 수 설정에 따라 다릅니다. 10~15초 간격으로 조회 API를 폴링하는 것을 권장합니다.

결과물 링크와 작업의 유효 기간은 얼마나 되나요?

  • 작업 ID는 생성 시점부터 24시간 동안 조회할 수 있으며, 응답의 expires_at 필드가 조회 마감 시각입니다.
  • content_url / preview_url은 업스트림 임시 링크로 일정 시간이 지나면 만료되므로, 작업 완료 후 가능한 한 빨리 다운로드하여 저장하세요.

prompt와 참조 이미지를 동시에 전달할 수 있나요?

불가능합니다. 둘은 상호 배타적입니다. 유일한 예외는 generate_type: "Sketch"(스케치-3D)로, 스케치 이미지와 텍스트 설명을 동시에 전달할 수 있습니다.

generate_type의 각 유형은 어떤 차이가 있나요?

작업이 실패하면 어떻게 처리하나요?

statusfailed일 때, 응답의 error 필드에 오류 정보가 포함됩니다.
일반적인 실패 원인으로는 콘텐츠 위반, 이미지 형식 미지원, 참조 이미지 접근 불가 등이 있습니다. 오류 정보에 따라 조정한 후 재시도하세요.
마지막 업데이트: 2026-07-17