본문으로 건너뛰기
PleumRouter
시작하기

3D Generation

BytePlus ModelArk에서 Hyper3D 또는 Hitem3D 메시를 비동기 작업으로 생성합니다.

POST /v1/3d/generations는 즉시 job_id를 반환합니다. 완료될 때까지 GET /v1/jobs/{job_id}를 폴링하세요. 모든 요청에는 plm_ API 키가 필요합니다.

POST/v1/3d/generations

작업 제출#

파라미터타입필수설명
modelstring필수3D 모델 ID. 예: Hyper3d-Rodin-Gen2, Hitem3d-2.0.
promptstring | null선택텍스트 설명. 모든 모델에서 최대 400자입니다. prompt 또는 images 중 하나는 필요합니다.
imagesstring[]선택HTTP(S) 이미지 reference URL. 전체 상한은 5장이지만 Hitem3D에는 1~4장이 필요합니다.
generation_modestandard_white | standard_textured | high_precision_white | high_precision_textured선택Hitem3D 필수 가격 모드입니다. 해당 resolution/request_type을 원자적으로 고정합니다.
mesh_optionsobject선택Hyper3D 전용 구조화 mesh 제어입니다(material, mesh_mode, quality_override 등). Hitem3D에서는 generation_mode와 함께 사용할 수 없습니다.
output_formatglb | obj | stl | fbx | usdz선택선호하는 결과 파일 형식입니다.
seedinteger선택Hyper3D 전용 0~65,535 seed입니다. Hitem3D에는 전달할 수 없습니다.
request
curl https://apirouter.pleum.ai/v1/3d/generations \
  -H "Authorization: Bearer $PLEUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-mesh-001" \
  -d '{
    "model": "Hitem3d-2.0",
    "images": ["https://example.com/product.png"],
    "generation_mode": "high_precision_textured",
    "output_format": "glb"
  }'
submit + poll (Python)
import os, time, requests

BASE = "https://apirouter.pleum.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['PLEUM_API_KEY']}",
    "Content-Type": "application/json",
}

# 1. Submit the job — returns job_id immediately.
resp = requests.post(f"{BASE}/3d/generations", headers=HEADERS, json={
    "model": "Hitem3d-2.0",
    "images": ["https://example.com/product.png"],
    "generation_mode": "high_precision_textured",
    "output_format": "glb",
})
job_id = resp.json()["job_id"]

# 2. Poll until the job finishes.
while True:
    job = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS).json()
    if job["status"] != "processing":
        break
    time.sleep(5)

print(job["result_url"] if job["status"] == "succeeded" else job["error"])
submit + poll (TypeScript)
const BASE = "https://apirouter.pleum.ai/v1";
const HEADERS = {
  Authorization: `Bearer ${process.env.PLEUM_API_KEY}`,
  "Content-Type": "application/json",
};

// 1. Submit the job — returns job_id immediately.
const submit = await fetch(`${BASE}/3d/generations`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({
    model: "Hitem3d-2.0",
    images: ["https://example.com/product.png"],
    generation_mode: "high_precision_textured",
    output_format: "glb",
  }),
});
const { job_id } = await submit.json();

// 2. Poll until the job finishes.
let job: any;
do {
  await new Promise((r) => setTimeout(r, 5000));
  job = await (await fetch(`${BASE}/jobs/${job_id}`, { headers: HEADERS })).json();
} while (job.status === "processing");

console.log(job.status === "succeeded" ? job.result_url : job.error);
200 OK
{
  "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "processing",
  "model": "Hitem3d-2.0",
  "result_url": null,
  "cost": null,
  "error": null,
  "assets": []
}

BytePlus ModelArk 모델 규칙#

모델별 입력·형식·가격 모드는 크레딧 차감 전에 검증됩니다. 지원하지 않는 조합은 비용 없이 400을 반환합니다.

파라미터타입필수설명
Hyper3D Rodin Gen2text-to-3D / image-to-3D선택prompt 또는 최대 5장의 image reference를 받습니다. generation_mode는 허용되지 않으며 Hyper3D mesh_options와 seed를 사용할 수 있습니다.
Hitem3D 2.0image-to-3D선택1~4장의 image reference와 generation_mode가 모두 필요합니다. standard/high-precision × white/textured 중 하나를 고르면 공식 variant와 가격이 함께 고정됩니다.

작업 폴링#

GET/v1/jobs/{job_id}

POST 응답은 처음에 processing입니다. GET /v1/jobs/{job_id}가 같은 작업 객체를 반환하며, 성공 시 assets에 GLB/OBJ/STL/FBX/USDZ 파일이 포함될 수 있고 result_url은 대표 URL입니다.

succeeded
{
  "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "succeeded",
  "model": "Hitem3d-2.0",
  "result_url": "https://cdn.pleum.ai/3d/f47ac10b-58cc-4372-a567-0e02b2c3d479.glb",
  "cost": {"krw": 2900},
  "error": null,
  "assets": [
    {"type": "3d", "url": "https://cdn.pleum.ai/3d/f47ac10b-58cc-4372-a567-0e02b2c3d479.glb", "format": "glb"}
  ]
}

정산 및 BYOK#

비동기 3D 작업은 제출 시점의 모델·가격·환율이 정산에 적용됩니다. Idempotency-Key는 선택 사항(최대 128자)입니다. 같은 키로 다시 제출하면 새 작업을 만들지 않고 처음 제출한 job_id를 반환합니다. 같은 키에 다른 본문을 보내면 422, 앞선 제출이 처리 중이면 409가 반환됩니다. 키는 24시간 동안 유지됩니다.

3D와 영상 같은 비동기 생성은 BYOK를 지원하지 않습니다. BYOK 키 요청은 400을 반환하고, 존재하지 않거나 내 소유가 아닌 job_id는 404를 반환합니다.
이전비디오 생성