3D

إنشاء نموذج 3D

ينشئ مهمة توليد نموذج 3D

POST
/v1/3d/generations

استخدم 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 فقط.

modelstringالافتراضي: tripo-h3.1

النموذج المراد استخدامه، على سبيل المثال tripo-h3.1 أو tripo-p1.0. استعلم عن GET /v1/models?recommended_for=3d قبل الاعتماد على نوع إدخال محدد أو تنسيق إخراج معين.

operationstring

text-to-3d أو image-to-3d. اختياري؛ يتم استنتاجه من المدخلات عند حذفه.

promptstringمطلوب

الوصف النصي لنموذج 3D المراد توليده، حتى 2000 حرف. يمكن أن تحدد النماذج حداً أقصر؛ راجع تفاصيلها. تتطلب طلبات Image-to-3D أيضاً prompt للنماذج الحالية؛ وبدونه يُرجع الطلب 400 prompt is required.

imagestring

صورة بترميز Base64 لتوليد image-to-3D.

image_urlstring

رابط URL عام لصورة لتوليد image-to-3D.

formatstring

تنسيق الإخراج؛ يعتمد الدعم والقيم المسموح بها على النموذج المحدد.

qualitystring

إعداد الجودة؛ يعتمد الدعم والقيم المسموح بها على النموذج المحدد.

stylestring

النمط المسبق للنموذج.

seedinteger

قيمة seed كعدد صحيح، عندما يدعمها النموذج المحدد.

userstring

معرّف فريد للمستخدم النهائي. أرسله فقط عندما يقبله النموذج المحدد.

تدرج بعض النماذج أيضاً n و negative_prompt و output_format (وهو اسم مستعار لـ format). لا تقم بإرسالها إلا عندما تدرجها تفاصيل النموذج.

الاستجابة

idstring

معرّف المهمة لاستطلاع الحالة.

task_idstring

اسم بديل لمعرّف المهمة غير المتزامنة عند إرجاعه بواسطة المحول.

poll_urlstring

رابط URL لحالة هذه المهمة. استعلم عبر GET /v1/tasks/{id} باستخدام id.

statusstring

حالة المهمة: pending، أو processing، أو completed، أو failed.

createdinteger

طابع زمني بتنسيق 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"
  }'

الاستجابة

Response
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "created": 1706000000,
  "model": "tripo-h3.1"
}

التفويض

BearerAuth
AuthorizationBearer <token>

مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.

الموضع: header

الترويسات

X-TokenLab-Delivery-Policy?string

سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.

القيم المتاحة

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

مفتاح اختياري يجعل طلب الإنشاء آمناً لإعادة المحاولة. أرسل قيمة فريدة جديدة، مثل UUID، لكل مهمة. إعادة المحاولة بنفس المفتاح ونفس نص الطلب تُرجع نتيجة طلب الإنشاء الأصلي، وعادةً ما تكون المهمة الأصلية، ولا تقوم بإنشاء أو إرسال أو احتساب تكلفة مهمة ثانية. يتم رفض نص الطلب المختلف الذي يستخدم مفتاحاً تم قبوله مسبقاً بالرمز 409. يتم تجاهل المفتاح الذي يتجاوز 255 حرفاً، وعندها لا يتمتع الطلب بحماية idempotency. راجع إعادة المحاولة بأمان باستخدام مفتاح idempotency.

الطول1 <= length <= 255

جسم الطلب

application/json

الاستجابة

application/json

application/json

application/json

application/json

application/json

application/json