3D
إنشاء نموذج 3D
ينشئ مهمة توليد نموذج 3D
استخدم GET /v1/models?recommended_for=3d للحصول على نماذج 3D الحالية.
قم بتوليد نماذج 3D من النصوص أو الصور. هذه API غير متزامنة. تُرجع استجابات الإنشاء معرّف المهمة. استعلم عبر GET /v1/tasks/{id} باستخدامه لمعرفة الحالة.
العملية هي text-to-3d أو image-to-3d. يمكنك حذف operation: الطلبات التي تحتوي على prompt فقط يتم التعامل معها كـ text-to-3d، والطلبات التي تحتوي على image أو image_url يتم التعامل معها كـ image-to-3d. إذا قمت بإرسال operation، فيجب أن تتطابق مع المدخلات: تتطلب image-to-3d وجود صورة، بينما لا تقبل text-to-3d أي صورة. تُرجع القيمة القديمة 3d-generation الخطأ 400 unsupported_operation. يدعم كل نموذج بعض العمليات فقط؛ تحقق من GET /v1/models/{model}.
جسم الطلب
قبل إرسال الحقول الاختيارية، تحقق من GET /v1/models/{model} لمعرفة المعلمات المقبولة للنموذج. يستخدم المثال model وprompt فقط.
tripo-h3.1النموذج المراد استخدامه، على سبيل المثال tripo-h3.1 أو tripo-p1.0. استعلم عن GET /v1/models?recommended_for=3d قبل الاعتماد على نوع إدخال محدد أو تنسيق إخراج معين.
text-to-3d أو image-to-3d. اختياري؛ يتم استنتاجه من المدخلات عند حذفه.
الوصف النصي لنموذج 3D المراد توليده، حتى 2000 حرف. يمكن أن تحدد النماذج حداً أقصر؛ راجع تفاصيلها. تتطلب طلبات Image-to-3D أيضاً prompt للنماذج الحالية؛ وبدونه يُرجع الطلب 400 prompt is required.
صورة بترميز Base64 لتوليد image-to-3D.
رابط URL عام لصورة لتوليد image-to-3D.
تنسيق الإخراج؛ يعتمد الدعم والقيم المسموح بها على النموذج المحدد.
إعداد الجودة؛ يعتمد الدعم والقيم المسموح بها على النموذج المحدد.
النمط المسبق للنموذج.
قيمة seed كعدد صحيح، عندما يدعمها النموذج المحدد.
معرّف فريد للمستخدم النهائي. أرسله فقط عندما يقبله النموذج المحدد.
تدرج بعض النماذج أيضاً n و negative_prompt و output_format (وهو اسم مستعار لـ format). لا تقم بإرسالها إلا عندما تدرجها تفاصيل النموذج.
الاستجابة
معرّف المهمة لاستطلاع الحالة.
اسم بديل لمعرّف المهمة غير المتزامنة عند إرجاعه بواسطة المحول.
رابط URL لحالة هذه المهمة. استعلم عبر GET /v1/tasks/{id} باستخدام id.
حالة المهمة: pending، أو processing، أو completed، أو failed.
طابع زمني بتنسيق Unix لوقت إنشاء المهمة.
الطلب
curl -X POST "https://api.tokenlab.sh/v1/3d/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "tripo-h3.1",
"prompt": "A detailed medieval castle with towers"
}'الاستجابة
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"created": 1706000000,
"model": "tripo-h3.1"
}التفويض
BearerAuth مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.
الموضع: header
الترويسات
سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.
القيم المتاحة
- "auto"
- "verified"
- "official"
مفتاح اختياري يجعل طلب الإنشاء آمناً لإعادة المحاولة. أرسل قيمة فريدة جديدة، مثل UUID، لكل مهمة. إعادة المحاولة بنفس المفتاح ونفس نص الطلب تُرجع نتيجة طلب الإنشاء الأصلي، وعادةً ما تكون المهمة الأصلية، ولا تقوم بإنشاء أو إرسال أو احتساب تكلفة مهمة ثانية. يتم رفض نص الطلب المختلف الذي يستخدم مفتاحاً تم قبوله مسبقاً بالرمز 409. يتم تجاهل المفتاح الذي يتجاوز 255 حرفاً، وعندها لا يتمتع الطلب بحماية idempotency. راجع إعادة المحاولة بأمان باستخدام مفتاح idempotency.
1 <= length <= 255جسم الطلب
application/json
الاستجابة
application/json
application/json
application/json
application/json
application/json
application/json