본문으로 건너뛰기

tripo/h3.1/image-to-3d

Tripo H3.1 Image to 3D는 이미지 한 장을 기본으로 PBR 텍스처가 입혀진 GLB로 만들며, 고해상도 텍스처, 정밀 형상, 쿼드 토폴로지, 면 수, 실제 크기 스케일, 방향, 형상과 텍스처 각각의 시드를 스위치로 고릅니다.

최저가 $0.432/회

플레이그라운드

요청 보내기

빠른 시작

예시는 선택한 엔드포인트의 공개 파라미터 정의를 사용합니다. API 키와 예시 미디어를 바꾼 뒤 서버에서 요청하세요.

SDK 및 연동
POSThttps://api.spicyapi.ai/api/v1/jobs/createTask

API 인증

API 키는 서버 환경 변수 SPICY_API_KEY에 보관하세요. Bearer 인증을 사용하고 JSON 요청에는 Content-Type: application/json을 지정하세요.

Authorization: Bearer $SPICY_API_KEY
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  -d '{
  "model": "tripo/h3.1/image-to-3d",
  "input": {
    "generate_parts": false,
    "generate_pbr": true,
    "generate_texture": true,
    "geometry_quality": "standard",
    "image_url": "https://example.com/reference.png",
    "low_poly": false
  }
}'

# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
  -H "Authorization: Bearer $SPICY_API_KEY"

이 모델의 입력 스키마에서 뽑아낸 예시입니다. API도 모든 요청을 같은 스키마로 검증합니다.

입력 파라미터

이 필드들은 요청 본문의 input 객체 안에 넣습니다. 이름과 타입은 API와 동일합니다. 기본값이 적혀 있지 않은 필드는 임의로 가정하지 마세요.

image_urlstring필수

모델로 만들 이미지. JPEG, PNG, WebP, 최대 10MB. 피사체 하나가 단색 배경에서 프레임 안에 모두 들어오게 하세요. 45도 각도가 깊이 정보를 가장 많이 줍니다.

기본값
지정되지 않음
제약 조건
minLength:1
contentMediaType:["image/jpeg","image/png","image/webp","image/gif"]
texture_seedinteger선택

텍스처 단계의 선택 시드. seed를 고정하고 이것을 바꾸면 같은 형태에 새 텍스처를 시험할 수 있습니다.

기본값
지정되지 않음
제약 조건
minimum:0
maximum:2147483647
seedinteger선택

형상 단계의 선택 시드. 고정하면 같은 형태를 재현합니다.

기본값
지정되지 않음
제약 조건
minimum:0
maximum:2147483647
uv_unwrapboolean선택

기본 켜짐. 끄면 UV 언래핑을 건너뛰어 더 빠르고 작은 파일이 나오지만, 메시에 나중에 텍스처를 입히기 위한 텍스처 좌표가 없게 됩니다. 가격은 변하지 않습니다.

기본값
true
auto_sizeboolean선택

기본 꺼짐. 켜면 추정한 실제 크기로 메시를 스케일링해 AR과 프린트에 유용합니다. 가격은 변하지 않습니다.

기본값
false
texture_alignmentstring선택

original_image(기본값)는 텍스처를 이미지에, geometry는 생성된 형태에 맞춥니다. 가격은 변하지 않습니다.

기본값
"original_image"
허용 값
"original_image""geometry"
model_orientationstring선택

default는 모델 기본 방향을 유지하고, align_image는 이미지의 시점에 맞게 결과를 회전합니다. 가격은 변하지 않습니다.

기본값
"default"
허용 값
"default""align_image"
image_autofixboolean선택

기본 꺼짐. 켜면 모델링 전에 흐리거나 노이즈가 많거나 저해상도인 이미지를 보정하며, 시간이 더 걸립니다. 가격은 변하지 않습니다.

기본값
false
face_limitinteger선택

선택 사항인 목표 면 수, 1,000~2,000,000. 비워 두면 모델이 정하며 100만 면을 넘을 수 있습니다. 대부분의 웹 뷰어에는 5만~20만이 맞습니다. 가격은 변하지 않습니다.

기본값
지정되지 않음
제약 조건
minimum:1000
maximum:2000000
generate_partsboolean선택요금에 영향

기본 꺼짐. 켜면 모델을 하나의 GLB 안에 이름이 붙은 개별 파트로 돌려줍니다(우리 장난감 우주비행사 기준 18개 파트). 파트에는 텍스처가 없고 항상 삼각형이므로 텍스처 옵션과 quad_mesh는 무시되며 과금되지 않습니다. 그래도 총 가격은 텍스처를 입힌 기본 설정보다 높습니다.

기본값
false
low_polyboolean선택요금에 영향

기본 꺼짐. 켜면 깔끔하고 손으로 모델링한 듯한 토폴로지의 가벼운 메시를 만들며, 단순한 소품에 가장 적합합니다. face_limit는 20,000 이하로 유지하세요. 검증 실행에서 부츠에 face_limit 5,000을 적용했을 때 7,675 삼각면이 나왔습니다. 가격에 더해집니다.

기본값
false
quad_meshboolean선택요금에 영향

기본 꺼짐. 켜면 삼각형 대신 사각형 폴리곤으로 돌려주어 모델링 툴에서 편집하기 쉽고, 이때 파일은 GLB가 아닌 FBX(텍스처 내장)로 옵니다. 가격에 조금 더해집니다. generate_parts가 켜져 있으면 무시되며 과금되지 않습니다. 파트는 GLB 안에서 삼각형으로 남습니다.

기본값
false
geometry_qualitystring선택요금에 영향

standard(기본값) 또는 detailed. detailed는 표면 디테일을 더 세밀하게 만들며 가장 비싼 추가 옵션입니다.

기본값
"standard"
허용 값
"standard""detailed"
remove_lightingboolean선택

기본 켜짐. 텍스처를 입히기 전에 이미지에 구워진 하이라이트와 그림자를 제거해서, 모델이 사용자 장면의 조명에 반응하게 합니다. v3.5 텍스처 모델에서만 적용됩니다. 가격은 변하지 않습니다.

기본값
true
texture_versionstring선택

v3.0-20250812(기본값) 또는 새 버전인 v3.5-20260815. texture_quality의 fast와 remove_lighting은 v3.5에 의존합니다. 가격은 변하지 않습니다.

기본값
"v3.0-20250812"
허용 값
"v3.0-20250812""v3.5-20260815"
texture_qualitystring선택요금에 영향

standard(기본값), detailed, extreme 또는 fast 중 하나입니다. detailed는 고해상도 텍스처를, extreme은 8K 텍스처를 만들며 둘 다 가격에 더해집니다. fast는 표준 크기를 유지하고 v3.5 텍스처 모델을 쓰며 가격은 standard와 같습니다. 어느 것도 텍스처 없는 메시나 generate_parts에는 적용되지 않습니다.

기본값
"standard"
허용 값
"standard""detailed""extreme""fast"
generate_pbrboolean선택요금에 영향

기본 켜짐. 베이스 컬러에 더해 PBR 머티리얼 맵(메탈릭-러프니스, 노멀)을 만들고, generate_texture가 꺼져 있어도 텍스처를 켭니다. generate_texture와 함께 끄면 더 싼 맨 메시가 됩니다.

기본값
true
generate_textureboolean선택요금에 영향

기본 켜짐. 메시에 텍스처를 입힙니다. 이걸 꺼도 generate_pbr까지 꺼야 텍스처 추가 요금이 빠집니다. PBR 머티리얼이 텍스처를 다시 켜기 때문입니다.

기본값
true

작업 추적

HTTP 202는 접수되었다는 뜻이며 생성 완료가 아닙니다. 반환된 taskId를 저장하고 같은 작업을 조회하세요. 결과를 기다리는 동안 작업을 다시 생성하지 마세요.

접수 응답
HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3

{
  "code": 200,
  "msg": "success",
  "request_id": "req_example_create",
  "data": {
    "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "state": "queued",
    "estimatedCost": "0.750000"
  }
}

접수 응답에 이번 예상 비용이 포함되므로 앱의 작업 기록과 청구 화면에 같은 금액을 표시할 수 있습니다.

작업 조회
curl --get "https://api.spicyapi.ai/api/v1/jobs/recordInfo" \
  --data-urlencode "taskId=$TASK_ID" \
  -H "Authorization: Bearer $SPICY_API_KEY"

약 2초 간격으로 시작해서 점점 간격을 넓히세요. 종료 상태가 나오면 멈추고, 연결이 끊겼더라도 원래 taskId를 그대로 조회하세요. 다시 생성할 때는 처음에 쓴 Idempotency-Key와 본문을 그대로 써야 합니다.

아니면 콜백이 찾아오게 하세요
import { verifyWebhook } from "@spicyapi/sdk";

// express.raw keeps the bytes we signed; express.json never matches.
app.post("/hooks/spicy", express.raw({ type: "application/json" }), (req, res) => {
  const { payload } = verifyWebhook({
    rawBody: req.body,
    timestamp: req.header("X-Webhook-Timestamp"),
    signature: req.header("X-Webhook-Signature"),
    payloadVersion: Number(req.header("X-Webhook-Payload-Version")),
    secret: process.env.SPICY_WEBHOOK_SECRET,
  });
  res.status(200).end();
  void handleFinishedTask(payload);
});

작업을 만들 때 callBackUrl을 넘기면 완료된 레코드가 POST로 전달됩니다 — 폴링 루프가 아예 필요 없습니다. 모든 전달에는 X-Webhook-Timestamp, X-Webhook-Signature, X-Webhook-Payload-Version이 함께 옵니다. 서명은 taskId.timestamp.sha256(body)에 대한 base64 HMAC-SHA256이므로 반드시 원본 바이트로 검증해야 합니다. JSON을 파싱했다가 다시 직렬화하면 바이트가 달라져 검증이 실패합니다. 실패한 전달은 재시도되므로 같은 taskId가 두 번 올 수 있습니다. 핸들러를 멱등하게 만드세요. 먼저 2xx로 답하고 처리는 그다음에 — 응답이 느리면 전달 실패로 간주됩니다.

결과 읽기

state가 succeeded일 때만 output을 사용하세요. 실패 시 errorCode, errorMessage, request_id로 원인을 확인하세요. 예시 비용과 상태는 실제 청구 내역이 아닙니다.

완료 응답 예시
{
  "code": 200,
  "msg": "success",
  "request_id": "req_example_record",
  "data": {
    "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "model": "tripo/h3.1/image-to-3d",
    "state": "succeeded",
    "output": {
      "assets": [
        {
          "key": "tasks/2026/08/28/job_01k3m8x9q2z4v7n5p6r8s0t1w3/3f7a1c9e5b2d48f0a6c1e3d5b7f9a1c3.png",
          "mime": "image/png",
          "url": "https://example.r2.cloudflarestorage.com/results/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.png?X-Amz-Signature=SIGNATURE_FROM_RESPONSE",
          "expiresAt": "2026-08-28T12:20:08.000Z"
        }
      ]
    },
    "cost": "0.750000",
    "settled": true,
    "createdAt": "2026-08-28T12:00:00Z",
    "completedAt": "2026-08-28T12:00:30Z"
  }
}

사용 가능한 파일은 assets[].url에서 바로 열거나 다운로드할 수 있으며 API Authorization 헤더가 필요하지 않습니다. 서명 URL은 expiresAt에 만료됩니다. 보관 기간 내에 작업을 다시 조회하면 URL이 갱신됩니다. 처리 중이거나 사용할 수 없는 파일에는 URL이 없습니다. 서명 URL은 비공개로 보관하세요.

SDK 및 연동

앱, 터미널, AI 어시스턴트 또는 시각적 워크플로에서 SpicyAPI를 사용하세요. 원하는 설정 가이드를 선택하세요.

ComfyUI에서 쓰기

ComfyUI Manager나 아래 명령으로 SpicyAPI 노드를 설치한 뒤 캔버스에서 Tripo H3.1 · Image to 3D를 검색하세요. 노드는 이 페이지와 같은 옵션을 제공하며, 실행하기 전에 가격을 보여 줍니다.

cd ComfyUI/custom_nodes
git clone https://github.com/spicyapi-ai/comfyui-spicyapi