دليل المطور الشامل لاستخدام Tripo 3D API

لقد غيَّرت القدرة على إنشاء نماذج ثلاثية الأبعاد من الأوصاف النصية أو الصور طريقة بناء المطورين للتطبيقات الخاصة بالألعاب والتجارة الإلكترونية والواقع الافتراضي والتصوير المعماري. يوفر Tripo 3D API طريقة مباشرة لدمج إنشاء النماذج ثلاثية الأبعاد المدعومة بالذكاء الاصطناعي في تطبيقاتك دون الحاجة إلى خبرة واسعة في النمذجة ثلاثية الأبعاد.

💡

هل تريد أداة رائعة لاختبار واجهات برمجة التطبيقات (API Testing) تُنتج توثيقًا جميلًا لواجهة برمجة التطبيقات؟

هل تريد منصة متكاملة وشاملة لفريق المطورين لديك للعمل معًا بأقصى قدر من الإنتاجية؟

Apidog يلبي جميع متطلباتك، ويحل محل Postman بسعر أكثر بأسعار معقولة بكثير!

button

يرشدك هذا الدليل عبر كل ما تحتاجه لتطبيق Tripo 3D API، من الإعداد الأولي إلى النشر في بيئة الإنتاج.

ما هو Tripo 3D API؟

يحوّل Tripo 3D API المطالبات النصية أو الصور ثنائية الأبعاد إلى نماذج ثلاثية الأبعاد جاهزة للإنتاج من خلال خوارزميات الذكاء الاصطناعي المتقدمة. تتعامل الخدمة مع عمليات التعلم الآلي المعقدة وراء الكواليس، وتكشف عن نقاط نهاية REST بسيطة يمكن للمطورين دمجها في غضون دقائق.

يمكنك الوصول إلى Tripo 3D API واستخدامه بتكلفة منخفضة في Hypereal AI.

تدعم المنصة ثلاثة أوضاع رئيسية للإنشاء:

النص إلى 3D: إنشاء نماذج من أوصاف اللغة الطبيعية
الصورة إلى 3D: تحويل صورة واحدة أو صور متعددة إلى كائنات ثلاثية الأبعاد
من منظورات متعددة إلى 3D: إنشاء نماذج عالية الدقة من منظورات صور متعددة

يتم تصدير النماذج المُنشأة بتنسيقات قياسية تشمل GLB وGLTF وFBX وOBJ، مما يجعلها متوافقة مع معظم برامج 3D ومحركات الألعاب.

البدء: المصادقة والإعداد

الخطوة 1: إنشاء مفتاح API الخاص بك

قبل إجراء أي مكالمات لـ API، تحتاج إلى بيانات اعتماد المصادقة:

قم بزيارة صفحة توثيق منصة Tripo 3D

2. انقر على "إنشاء مفتاح API جديد"

3. انسخ مفتاحك على الفور (يبدأ بـ tsk_)

4. قم بتخزينه بشكل آمن، لا يمكنك استعادته مرة أخرى بعد إغلاق النافذة

ملاحظة أمنية: لا تكشف أبدًا عن مفاتيح API في كود جانب العميل أو المستودعات العامة. استخدم متغيرات البيئة أو خدمات إدارة الأسرار الآمنة.

الخطوة 2: تثبيت Python SDK (اختياري)

بينما يمكنك استخدام REST API مباشرة مع أي عميل HTTP، فإن Python SDK الرسمي يبسط عملية التكامل:

pip install tripo3d

يتعامل SDK مع المصادقة واستقصاء المهام غير المتزامن وتنزيل الملفات تلقائيًا.

الخطوة 3: التحقق من إعداداتك

اختبر مصادقتك باستخدام طلب cURL الأساسي هذا:

export TRIPO_API_KEY="tsk_your_actual_key_here"

curl https://api.tripo3d.ai/v2/openapi/task \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${TRIPO_API_KEY}" \
  -d '{"type": "text_to_model", "prompt": "a simple wooden chair"}'

يُرجع الرد الناجح معرف مهمة (task ID)، مما يشير إلى أن مصادقتك تعمل بشكل صحيح.

الطريقة 1: إنشاء نموذج ثلاثي الأبعاد من النص

التطبيق الأساسي

يحول إنشاء نماذج ثلاثية الأبعاد من النص الأوصاف باللغة الطبيعية إلى كائنات ثلاثية الأبعاد. وهذا يعمل بشكل جيد لإنشاء أصول من الأوصاف المفاهيمية.

مثال Python SDK:

import asyncio
from tripo3d import TripoClient, TaskStatus

async def generate_from_text():
    async with TripoClient(api_key="YOUR_API_KEY") as client:
        # Submit generation task
        task_id = await client.text_to_model(
            prompt="a vintage leather armchair with wooden legs",
            negative_prompt="low quality, blurry, distorted",
            model_version="v2.5"
        )

        print(f"Task submitted: {task_id}")

        # Wait for completion
        task = await client.wait_for_task(task_id, verbose=True)

        # Download results
        if task.status == TaskStatus.SUCCESS:
            files = await client.download_task_models(task, "./output")
            for model_type, path in files.items():
                print(f"Downloaded {model_type}: {path}")
        else:
            print(f"Task failed: {task.status}")

asyncio.run(generate_from_text())

مثال REST API:

curl -X POST https://api.tripo3d.ai/v2/openapi/task \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${TRIPO_API_KEY}" \
  -d '{
    "type": "text_to_model",
    "prompt": "a vintage leather armchair with wooden legs",
    "negative_prompt": "low quality, blurry, distorted",
    "model_version": "v2.5"
  }'

فهم المعاملات

المعامل	النوع	مطلوب	الوصف
prompt	string	نعم	وصف تفصيلي للنموذج ثلاثي الأبعاد المطلوب
negative_prompt	string	لا	الخصائص التي يجب تجنبها في عملية الإنشاء
model_version	string	لا	إصدار واجهة برمجة التطبيقات (افتراضي: الأحدث)

نصائح هندسة المطالبات

كن محددًا بشأن المواد والألوان والأشكال
قم بتضمين واصفات الأنماط (واقعي، كرتوني، مضلعات قليلة)
اذكر المراجع القياسية عند الاقتضاء
أضف تفضيلات الإضاءة لتحسين توليد الزخارف (الخامات)

الطريقة 2: إنشاء نموذج ثلاثي الأبعاد من الصورة

تحويل صورة واحدة

حوّل صورة فوتوغرافية أو رسم توضيحي واحدًا إلى نموذج ثلاثي الأبعاد. يعمل هذا بشكل أفضل مع الصور الواضحة والمضاءة جيدًا التي تظهر الكائن من زاوية مباشرة.

مثال Python SDK:

import asyncio
from tripo3d import TripoClient, TaskStatus

async def generate_from_image():
    async with TripoClient(api_key="YOUR_API_KEY") as client:
        task_id = await client.image_to_model(
            image="./path/to/product-photo.jpg",
            texture_quality="high",
            auto_scale=True,
            face_limit=50000
        )

        print(f"Processing image: {task_id}")

        task = await client.wait_for_task(task_id, verbose=True)

        if task.status == TaskStatus.SUCCESS:
            files = await client.download_task_models(task, "./models")
            print(f"Model saved to: {files}")

asyncio.run(generate_from_image())

معاملات متقدمة

المعامل	النوع	الافتراضي	الوصف
texture_seed	عدد صحيح	عشوائي	بذرة لتوليد نسيج قابل للتكرار
auto_scale	قيمة منطقية	خطأ	تحجيم النموذج إلى الأبعاد الواقعية
quad	قيمة منطقية	خطأ	توليد شبكة رباعية (+$0.05 لكل مهمة)
texture_quality	سلسلة نصية	"original_image"	أولوية محاذاة النسيج
orientation	سلسلة نصية	"default"	قم بالتعيين على "align_image" للتدوير التلقائي
face_limit	عدد صحيح	متغير	يتحكم في عدد المضلعات للتحسين

الإنشاء متعدد المنظورات

للحصول على نتائج بجودة أعلى، قم بتوفير زوايا متعددة لنفس الكائن:

async def generate_from_multiview():
    async with TripoClient(api_key="YOUR_API_KEY") as client:
        task_id = await client.multiview_to_model(
            images=[
                "./front-view.jpg",
                "./side-view.jpg",
                "./top-view.jpg"
            ],
            texture_quality="high"
        )

        task = await client.wait_for_task(task_id, verbose=True)

        if task.status == TaskStatus.SUCCESS:
            files = await client.download_task_models(task, "./output")

ينتج التوليد متعدد المنظورات تفاصيل هندسية وملمسية أفضل بكثير مقارنة بتحويل صورة واحدة.

فهم حالة المهمة والاستقصاء

يعالج Tripo 3D API الطلبات بشكل غير متزامن. بعد إرسال مهمة، تقوم بالاستقصاء لإكمالها بدلاً من الحظر.

دورة حياة المهمة

تم الإرسال (Submitted): تم قبول المهمة ووضعها في قائمة الانتظار
المعالجة (Processing): نموذج الذكاء الاصطناعي يقوم بإنشاء مخرجات 3D
نجاح (Success): النموذج جاهز للتنزيل
فشل (Failed): حدث خطأ في عملية الإنشاء

الاستقصاء اليدوي (REST API)

curl https://api.tripo3d.ai/v2/openapi/task/{task_id} \
  -H "Authorization: Bearer ${TRIPO_API_KEY}"

بنية الاستجابة:

{
  "code": 0,
  "data": {
    "task_id": "abc123",
    "status": "success",
    "output": {
      "model": "https://download-url/model.glb",
      "pbr_model": "https://download-url/model-pbr.glb"
    }
  }
}

الاستقصاء التلقائي (Python SDK)

يتولى SDK عملية الاستقصاء تلقائيًا:

task = await client.wait_for_task(
    task_id,
    verbose=True,  # Show progress updates
    timeout=300    # Maximum wait time in seconds
)

نظام التسعير والائتمانات

يستخدم Tripo نموذج تسعير قائم على الائتمانات حيث تستهلك العمليات المختلفة كميات متفاوتة من الائتمانات.

فئات التسعير

الخطة	السعر	ائتمانات شهرية	مهام متزامنة
أساسية	مجاني	300	1
احترافية	$15.90/شهر*	3,000	10
متقدمة	$39.90/شهر*	8,000	15

*الفواتير السنوية: خصم 20% (190.80 دولارًا أمريكيًا سنويًا للاحترافية، 478.80 دولارًا أمريكيًا سنويًا للمتقدمة)

تكاليف الائتمان

النص إلى 3D: ~30 ائتمانًا لكل عملية إنشاء
الصورة إلى 3D: ~30-50 ائتمانًا حسب إعدادات الجودة
متعدد المنظورات إلى 3D: ~60-80 ائتمانًا
مخرجات الشبكة الرباعية (Quad mesh): 0.05 دولارًا إضافيًا (حوالي 5 ائتمانات)

نصائح لتحسين التكلفة

استخدم قيم face_limit أقل لتوليد المعاينات
اختبر بالخطة الأساسية قبل الانتقال إلى الفئات المدفوعة
اجمع الطلبات المتشابهة لزيادة حدود المهام المتزامنة
قم بتخزين النماذج المُنشأة مؤقتًا لتجنب إعادة إنشاء الأصول المتطابقة

معالجة الأخطاء وأفضل الممارسات

التعامل مع أخطاء API برشاقة

from tripo3d import TripoClient, TripoAPIError

async def safe_generation():
    try:
        async with TripoClient(api_key="YOUR_API_KEY") as client:
            task_id = await client.text_to_model(
                prompt="a detailed spaceship"
            )
            task = await client.wait_for_task(task_id)

            if task.status == TaskStatus.SUCCESS:
                files = await client.download_task_models(task, "./output")
                return files
            else:
                print(f"Generation failed: {task.status}")
                return None

    except TripoAPIError as e:
        if e.status_code == 401:
            print("Authentication failed. Check your API key.")
        elif e.status_code == 429:
            print("Rate limit exceeded. Wait before retrying.")
        elif e.status_code >= 500:
            print("Server error. Retry after a delay.")
        else:
            print(f"API error: {e}")
        return None

أفضل ممارسات الإنتاج

طبق منطق إعادة المحاولة للأعطال المؤقتة (أخطاء مستوى 500)
عيّن مهلات مناسبة بناءً على تعقيد المهمة
راقب استخدام الائتمان لمنع انقطاع الخدمة
تحقق من صحة المدخلات قبل إرسال العمليات المكلفة
خزن معرفات المهام (task IDs) لأغراض التصحيح والتدقيق
استخدم webhooks (إن وجدت) بدلاً من الاستقصاء المتكرر

تحديد المعدل

احترم حدود المهام المتزامنة بناءً على فئة خطتك. تجاوز الحدود يؤدي إلى أخطاء 429:

from asyncio import Semaphore

async def batch_generate(prompts, max_concurrent=10):
    semaphore = Semaphore(max_concurrent)

    async def generate_with_limit(prompt):
        async with semaphore:
            async with TripoClient(api_key="YOUR_API_KEY") as client:
                task_id = await client.text_to_model(prompt=prompt)
                return await client.wait_for_task(task_id)

    tasks = [generate_with_limit(p) for p in prompts]
    return await asyncio.gather(*tasks)

التكامل مع الأطر البرمجية الشائعة

تطبيق ويب Flask

from flask import Flask, request, jsonify
from tripo3d import TripoClient
import asyncio

app = Flask(__name__)

@app.route('/generate-3d', methods=['POST'])
def generate_model():
    data = request.json
    prompt = data.get('prompt')

    if not prompt:
        return jsonify({'error': 'Prompt required'}), 400

    async def generate():
        async with TripoClient(api_key="YOUR_API_KEY") as client:
            task_id = await client.text_to_model(prompt=prompt)
            return {'task_id': task_id}

    result = asyncio.run(generate())
    return jsonify(result)

@app.route('/check-status/')
def check_status(task_id):
    async def get_status():
        async with TripoClient(api_key="YOUR_API_KEY") as client:
            task = await client.get_task(task_id)
            return {'status': task.status}

    result = asyncio.run(get_status())
    return jsonify(result)

مثال Node.js Express

const express = require('express');
const axios = require('axios');
const app = express();

app.post('/generate', async (req, res) => {
  const { prompt } = req.body;

  try {
    const response = await axios.post(
      'https://api.tripo3d.ai/v2/openapi/task',
      {
        type: 'text_to_model',
        prompt: prompt
      },
      {
        headers: {
          'Authorization': `Bearer ${process.env.TRIPO_API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );

    res.json({ task_id: response.data.data.task_id });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

إدارة تكاملات API باستخدام Apidog

غالبًا ما تتكامل التطبيقات المعقدة مع العديد من واجهات برمجة التطبيقات (APIs) في وقت واحد. يصبح إدارة المصادقة، واختبار نقاط النهاية، ومراقبة الأداء عبر الخدمات المختلفة أمرًا صعبًا.

توفر Apidog إدارة موحدة لواجهات برمجة التطبيقات للمطورين الذين يعملون مع Tripo 3D API والخدمات الأخرى:

الميزات الرئيسية:

باني الطلبات المرئي: إنشاء مكالمات API بدون تنسيق JSON يدوي
إدارة البيئات: التبديل بين بيانات الاعتماد الخاصة بالتطوير، والاختبار، والإنتاج
الاختبار التلقائي: التحقق من الاستجابات واكتشاف مشكلات التكامل مبكرًا
التعاون الجماعي: مشاركة مجموعات API والوثائق مع المطورين
مراقبة الأداء: تتبع أوقات الاستجابة ومعدلات الأخطاء عبر جميع نقاط النهاية

قم باستيراد طلبات Tripo 3D API الخاصة بك إلى Apidog، واحفظها كقوالب، وقم بتنفيذها بنقرة واحدة. راقب أنماط استهلاك الائتمان وحدد فرص التحسين من خلال التحليلات المضمنة.

button

الخلاصة

يزيل Tripo 3D API الحواجز التقنية أمام دمج إنشاء النماذج ثلاثية الأبعاد المدعومة بالذكاء الاصطناعي في التطبيقات. تُمكّن واجهة REST المباشرة و Python SDK الرسمية المطورين من إضافة إمكانيات النص إلى 3D والصورة إلى 3D في غضون ساعات بدلاً من أسابيع.

ابدأ بالخطة الأساسية المجانية لإنشاء نموذج أولي لتكاملك. اختبر أنماط مطالبة مختلفة ومدخلات الصور لفهم جودة المخرجات. راقب أنماط استهلاك الائتمان قبل الالتزام بالفئات المدفوعة.

يتوسع نموذج المعالجة غير المتزامنة للمنصة بشكل جيد لأعباء عمل الإنتاج، بينما تضمن تنسيقات التصدير القياسية التوافق مع خطوط أنابيب 3D ومحركات الألعاب الحالية.