مدل سه‌بعدی

ساخت مدل سه‌بعدی

از یک توضیح متنی یا یک عکس از جسم، مدل سه‌بعدی GLB می‌سازد. پاسخ ۲۰۲ با شناسه‌ی کار است و هزینه برای هر ساخت ثابت است.

POST/v1/3d

یک prompt، یک image یا هر دو را بفرستید؛ صفحه‌ی هر مدل در /models می‌گوید کدام را می‌پذیرد. image را می‌توان به صورت فایل در multipart/form-data (حداکثر ۲۵ مگابایت)، یا در JSON به صورت URL یا data URL با base64 داد. URL با محافظ SSRF دریافت می‌شود و نوع فایل از روی بایت‌ها تشخیص داده می‌شود. بهترین نتیجه از عکس یک جسم تنها با پس‌زمینه‌ی ساده به دست می‌آید.

درخواست بلافاصله با 202 و status: queued جواب می‌گیرد. ساخت معمولاً بین بیست ثانیه تا چند دقیقه طول می‌کشد؛ GET /v1/3d/{id} را با فاصله صدا بزنید تا کار تمام شود و فایل را با /content بردارید.

حالت و جزئیات

هر مدل چند حالت دارد (preset)، مثل geometry برای شکل بدون بافت یا textured برای مدل بافت‌دار، و هر حالت قیمت خودش را دارد. بدون preset حالت پیش‌فرض مدل ساخته می‌شود. detail با مقدارهای low، medium و high تعداد چندضلعی‌ها را تعیین می‌کند و قیمت را تغییر نمی‌دهد؛ فقط مدل‌هایی که آن را فهرست کرده‌اند می‌پذیرند.

خروجی

خروجی همیشه یک فایل GLB است و بعضی مدل‌ها FBX، OBJ، USDZ یا STL هم می‌سازند؛ فهرست قالب‌های هر کار در output.formats می‌آید.

اگر کار شکست بخورد یا لغو شود، اعتبار رزروشده برمی‌گردد. عکس ورودی هنگام پایان کار از سیستم برداشته می‌شود، و این کارها در استودیو و گالری حساب شما دیده نمی‌شوند.

نمونه‌ها

curl https://1ai.ir/v1/3d \
  -H "Authorization: Bearer $ONEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "tripo/h3",
  "prompt": "a small red ceramic teapot"
}'
202پاسخ
{
  "id": "job_4Rw8xTq2NcYv6KpHm3Zs9B",
  "object": "3d.generation",
  "model": "tripo/h3",
  "status": "queued",
  "progress": 0,
  "created_at": 1795300000,
  "completed_at": null,
  "prompt": "a small red ceramic teapot",
  "preset": "textured",
  "detail": null,
  "estimated_credits": 6,
  "credits": 0,
  "output": null,
  "error": null
}

بدنه‌ی درخواست

  • modelstringالزامی

    شناسه‌ی مدل سه‌بعدی، برای نمونه tripo/h3.

  • promptstring

    توضیح جسم به انگلیسی، حداکثر ۶۰۰ نویسه. دست‌کم یکی از prompt و image لازم است.

  • imagefile

    عکس جسم: فایل در multipart، یا در JSON یک URL یا data URL.

  • presetstring

    حالت ساخت از فهرست حالت‌های مدل، مثل geometry یا textured. پیش‌فرض: حالت پیش‌فرض مدل.

  • detailstring

    سطح جزئیات هندسه، اگر مدل آن را بپذیرد.

    مقادیر مجاز:lowmediumhigh

خطاها

  • invalid_request400

    نه prompt آمده نه image، یا فیلد ناشناخته فرستاده شده است.

  • media_input_unsupported400

    مدل این نوع ورودی، این حالت یا این سطح جزئیات را نمی‌پذیرد.

  • input_fetch_failed400

    عکس از روی URL دریافت نشد.

  • model_kind_mismatch400

    مدل داده‌شده مدل سه‌بعدی نیست.

  • insufficient_credits402

    اعتبار برای رزرو هزینه کافی نیست.

  • model_not_found404

    مدل وجود ندارد یا کلید شما به آن دسترسی ندارد.

  • file_too_large413

    عکس آپلودشده از ۲۵ مگابایت بزرگ‌تر است.

صفحه‌های مرتبط