راهنمای اتصال به API

3D API؛ ساخت مدل سه‌بعدی از متن و عکس با کار پس‌زمینه و کلید API

ساخت مدل سه‌بعدی چند دقیقه طول می‌کشد، پس مسیر POST /v1/3d در وان ای آی (1ai) همیشه به صورت کار پس‌زمینه اجرا می‌شود: پاسخ 202 با یک شناسه‌ی job_ می‌گیرید، وضعیت را با GET /v1/3d/{id} می‌پرسید و بعد فایل را با GET /v1/3d/{id}/content برمی‌دارید. ورودی یک توصیف انگلیسی، یک عکس (لینک، data URL یا فایل multipart) یا هر دو است و با preset حالت ساخت و با detail میزان جزئیات را تعیین می‌کنید. هزینه هنگام ساخت کار رزرو و پس از پایان قطعی می‌شود.

ترمینال کد که مدل سه‌بعدی یک قوری را روی پایه می‌سازد، با نیمه‌ای به شکل اسکلت سه‌بعدی

چرا با 1ai

کار پس‌زمینه

درخواست فوراً با 202 و یک شناسه جواب می‌گیرد؛ لازم نیست اتصال را چند دقیقه باز نگه دارید.

از متن یا عکس

prompt، image یا هر دو؛ عکس را به صورت لینک عمومی، data URL یا فایل multipart بفرستید.

همه‌ی قالب‌های ساخته‌شده

پاسخ کار، قالب‌های آماده را در output.formats فهرست می‌کند و content?format=fbx هر کدام را برمی‌گرداند.

هزینه‌ی ثابت هر حالت

هر preset قیمت ثابت خودش را دارد؛ کار ناموفق یا لغوشده رزرو را آزاد می‌کند.

در چند قدم

  1. ۱

    کلید API بسازید

    از بخش توسعه‌دهندگان ← کلیدها یک کلید sk-1ai-… بسازید و در ONEAI_API_KEY نگه دارید.

  2. ۲

    کار را بسازید

    مدل و توصیف یا عکس را به https://1ai.ir/v1/3d بفرستید و شناسه‌ی job_ را از پاسخ 202 بردارید.

  3. ۳

    فایل را بردارید

    هر چند ثانیه وضعیت را بپرسید؛ وقتی status برابر succeeded شد، content لینک امضاشده‌ی فایل را برمی‌گرداند.

مدل‌های سه‌بعدی در API

همه‌ی مدل‌ها

Tripo H3

تریپو
مدل سه‌بعدی

مدل سه‌بعدی بافت‌دار از متن یا عکس، با خروجی GLB و FBX

۳۶ اعتبار / هر مدل سه‌بعدی (فقط شکل)
API

TRELLIS.2

مایکروسافت
مدل سه‌بعدی

مدل سه‌بعدی بافت‌دار از یک عکس؛ سریع و ارزان

۱۵ اعتبار / هر مدل سه‌بعدی (سریع)
API
مدل سه‌بعدی

شکل سه‌بعدی از متن یا عکس در کمتر از یک دقیقه

۴۰٫۵ اعتبار / هر مدل سه‌بعدی
API

Idol Max Turbo

اسپرید لبز
مدل سه‌بعدی

مدل سه‌بعدی شخصیت و شیء از یک عکس، ارزان و سریع

۱۵ اعتبار / هر مدل سه‌بعدی (استاندارد)
API
مدل سه‌بعدی

مدل سه‌بعدی تمیز با بافت از متن یا عکس، با چند قالب خروجی

۳۰ اعتبار / هر مدل سه‌بعدی (فقط شکل)
API

Rodin 2.5

هایپر تری‌دی
مدل سه‌بعدی

مدل سه‌بعدی باکیفیت با متریال PBR از متن یا عکس

۷۲ اعتبار / هر مدل سه‌بعدی (استاندارد)
API

Seed3D 2.0

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

مدل سه‌بعدی دقیق از یک عکس

۶۰ اعتبار / هر مدل سه‌بعدی
API

Hunyuan3D 3

تنسنت
مدل سه‌بعدی

مدل سه‌بعدی بافت‌دار یا کم‌چندضلعی برای بازی، از متن یا عکس

۶۷٫۵ اعتبار / هر مدل سه‌بعدی (فقط شکل)
API

Meshy 7.1

مشی
مدل سه‌بعدی

بهترین کیفیت مشی؛ مدل سه‌بعدی دقیق با بافت از متن یا عکس

۱۴۴ اعتبار / هر مدل سه‌بعدی (فقط شکل)
API

Tripo P2

تریپو
مدل سه‌بعدی

مدل حرفه‌ای تریپو؛ هندسه و بافت با جزئیات بالا از متن یا عکس

۱۸۰ اعتبار / هر مدل سه‌بعدی (فقط شکل)
API

Meshy T2

مشی
مدل سه‌بعدی

مدل سه‌بعدی سبک با بافت از متن یا عکس

۳۰ اعتبار / هر مدل سه‌بعدی (فقط شکل)
API

Tripo P1

تریپو
مدل سه‌بعدی

مدل سه‌بعدی بافت‌دار تریپو از متن یا عکس

۷۲ اعتبار / هر مدل سه‌بعدی (فقط شکل)
API

نمونه درخواست با curl

bash
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 with a curved spout"
  }'

پاسخ 202 شامل id (مثل job_…) و status: "queued" است.

نمونه با Python

python
import os, time, requests

base = "https://1ai.ir/v1"
headers = {"Authorization": f"Bearer {os.environ['ONEAI_API_KEY']}"}

job = requests.post(f"{base}/3d", headers=headers, json={
    "model": "microsoft/trellis-2",
    "image": "https://example.com/chair.png",
}).json()

while job["status"] in ("queued", "processing"):
    time.sleep(5)
    job = requests.get(f"{base}/3d/{job['id']}", headers=headers).json()

if job["status"] == "succeeded":
    glb = requests.get(f"{base}/3d/{job['id']}/content", headers=headers)
    open("model.glb", "wb").write(glb.content)

قالب‌ها و حالت‌ها

GLB همیشه ساخته می‌شود و پیش‌فرض content است. قالب‌های دیگر به مدل بستگی دارند و در output.formats می‌آیند. حالت‌های هر مدل (مثلاً فقط شکل یا شکل با بافت) و قیمت هرکدام در صفحه‌ی آن مدل فهرست شده‌اند؛ preset را نفرستید تا حالت پیش‌فرض ساخته شود.

سوالات متداول

ساخت هر مدل چقدر طول می‌کشد؟

بیشتر مدل‌ها در یک تا چند دقیقه تمام می‌شوند. هر ۵ تا ۱۰ ثانیه وضعیت را بپرسید؛ کاری که بیش از ۴۵ دقیقه طول بکشد ناموفق اعلام و رزرو آن آزاد می‌شود.

عکس را چطور بفرستم؟

در JSON، فیلد image یک لینک عمومی https یا یک data URL است. با multipart/form-data هم می‌توانید فایل را در فیلد image بفرستید. PNG و JPEG و WebP پذیرفته می‌شوند.

لینک فایل چقدر معتبر است؟

content یک لینک امضاشده با اعتبار یک ساعت برمی‌گرداند (302، یا با redirect=false در JSON). هر بار که لازم شد دوباره بخواهید؛ فایل تا وقتی کار را حذف نکنید می‌ماند.

مطالب مرتبط

استفاده از API سازگار با OpenAI در 1ai: راهنمای عملی با Python، Node.js و cURL
توسعه‌دهندگان

استفاده از API سازگار با OpenAI در 1ai: راهنمای عملی با Python، Node.js و cURL

چطور پروژه‌ای را که با کتابخانه‌ی OpenAI نوشته شده، فقط با تغییر آدرس پایه و کلید به 1ai وصل کنید؛ با نمونه کد Python، Node.js و cURL، استریم، فهرست مدل‌ها و مدیریت خطا.

۴ دقیقه مطالعه
کلید API در 1ai: امنیت، محدودیت‌ها و کنترل هزینه
توسعه‌دهندگان

کلید API در 1ai: امنیت، محدودیت‌ها و کنترل هزینه

چطور کلیدهای API را امن نگه دارید و هزینه را مهار کنید: مدل‌های مجاز، سقف اعتبار ماهانه، محدودیت نرخ، تاریخ انقضا، کلیدهای تیمی و گزارش مصرف.

۴ دقیقه مطالعه
همه‌ی امکانات

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

عکس یک جسم را بدهید یا آن را در چند کلمه توصیف کنید؛ چند دقیقه بعد مدل سه‌بعدی آن را در مرورگر می‌چرخانید و در قالب‌هایی مثل GLB دانلود می‌کنید.

OpenAI SDK

کتابخانه‌ی رسمی openai را در Python و Node.js با تغییر آدرس پایه به 1ai وصل کنید و چت، فراخوانی ابزار، بردار متن، تصویر و صدا را از یک کلید بگیرید.

3D API؛ ساخت مدل سه‌بعدی از متن و عکس با کار پس‌زمینه و کلید API

توصیف یا عکس جسم را بفرستید، شناسه‌ی کار را بگیرید و وقتی کار تمام شد فایل GLB یا هر قالب دیگری را که ساخته شده بردارید.

ساخت کلید API