Skip to content
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。
promptstring | null任意テキスト説明。最大 4,000 文字、Hyper3D では最大 400 文字。prompt または images のいずれかが必要です。
imagesstring[]任意HTTP(S) 画像参照 URL。全体上限は 5、Hitem3D は 1–4 枚必要です。
generation_modestandard_white | standard_textured | high_precision_white | high_precision_textured任意Hitem3D の必須価格モードで、対応する resolution/request_type を原子的に固定します。
mesh_optionsobject任意Hyper3D 専用の構造化メッシュ制御です。Hitem3D の generation_mode と組み合わせられません。
output_formatglb | obj | stl | fbx | usdz任意希望する結果ファイル形式。
seedinteger任意Hyper3D 専用の 0–65,535 seed。Hitem3D には送信できません。
charge_amount_krwinteger | null任意固定 KRW 精算額。通常 API キーは使用できず、first-party 委任キーのみ利用できます。
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 time, requests

BASE = "https://apirouter.pleum.ai/v1"
HEADERS = {"Authorization": "Bearer plm_...", "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"] in ("succeeded", "failed"):
        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 plm_...", "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 !== "succeeded" && job.status !== "failed");

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 モデル規則#

モデル固有の入力・形式・価格モードは credit hold 作成前に検証されます。未対応の組み合わせは課金なしで 400 を返します。

パラメータ型必須説明
Hyper3D Rodin Gen2text-to-3D / image-to-3D任意prompt または最大 5 枚の画像参照を受け取ります。generation_mode は使えず、Hyper3D mesh_options と seed を利用できます。
Hitem3D 2.0image-to-3D任意1–4 枚の画像参照と 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 ジョブは送信時に選択した offering・variant・為替・markup を保存し、完了時にそのスナップショットで精算します。Idempotency-Key は任意（最大 128 文字）で、同じ本文を 24 時間再生します。

3D や動画などの非同期生成は BYOK をサポートしません。BYOK キーのリクエストは 400 を返し、存在しないまたは所有していない job_id は 404 です。