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 قیمت ثابت خودش را دارد؛ کار ناموفق یا لغوشده رزرو را آزاد میکند.
در چند قدم
- ۱
کلید API بسازید
از بخش توسعهدهندگان ← کلیدها یک کلید sk-1ai-… بسازید و در ONEAI_API_KEY نگه دارید.
- ۲
کار را بسازید
مدل و توصیف یا عکس را به https://1ai.ir/v1/3d بفرستید و شناسهی job_ را از پاسخ 202 بردارید.
- ۳
فایل را بردارید
هر چند ثانیه وضعیت را بپرسید؛ وقتی status برابر succeeded شد، content لینک امضاشدهی فایل را برمیگرداند.
مدلهای سهبعدی در API
همهی مدلهاTripo H3
مدل سهبعدی بافتدار از متن یا عکس، با خروجی GLB و FBX
TRELLIS.2
مدل سهبعدی بافتدار از یک عکس؛ سریع و ارزان
Hunyuan 3D 3.1 Rapid
شکل سهبعدی از متن یا عکس در کمتر از یک دقیقه
Idol Max Turbo
مدل سهبعدی شخصیت و شیء از یک عکس، ارزان و سریع
Meshy T2.5
مدل سهبعدی تمیز با بافت از متن یا عکس، با چند قالب خروجی
Rodin 2.5
مدل سهبعدی باکیفیت با متریال PBR از متن یا عکس
Hunyuan3D 3
مدل سهبعدی بافتدار یا کمچندضلعی برای بازی، از متن یا عکس
Meshy 7.1
بهترین کیفیت مشی؛ مدل سهبعدی دقیق با بافت از متن یا عکس
Tripo P2
مدل حرفهای تریپو؛ هندسه و بافت با جزئیات بالا از متن یا عکس
Tripo P1
مدل سهبعدی بافتدار تریپو از متن یا عکس
نمونه درخواست با curl
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
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
چطور پروژهای را که با کتابخانهی OpenAI نوشته شده، فقط با تغییر آدرس پایه و کلید به 1ai وصل کنید؛ با نمونه کد Python، Node.js و cURL، استریم، فهرست مدلها و مدیریت خطا.

کلید API در 1ai: امنیت، محدودیتها و کنترل هزینه
چطور کلیدهای API را امن نگه دارید و هزینه را مهار کنید: مدلهای مجاز، سقف اعتبار ماهانه، محدودیت نرخ، تاریخ انقضا، کلیدهای تیمی و گزارش مصرف.
صفحههای مرتبط
همهی امکاناتساخت مدل سهبعدی
عکس یک جسم را بدهید یا آن را در چند کلمه توصیف کنید؛ چند دقیقه بعد مدل سهبعدی آن را در مرورگر میچرخانید و در قالبهایی مثل GLB دانلود میکنید.
OpenAI SDK
کتابخانهی رسمی openai را در Python و Node.js با تغییر آدرس پایه به 1ai وصل کنید و چت، فراخوانی ابزار، بردار متن، تصویر و صدا را از یک کلید بگیرید.
3D API؛ ساخت مدل سهبعدی از متن و عکس با کار پسزمینه و کلید API
توصیف یا عکس جسم را بفرستید، شناسهی کار را بگیرید و وقتی کار تمام شد فایل GLB یا هر قالب دیگری را که ساخته شده بردارید.
ساخت کلید API