Tripo3D

Guida alla migrazione da v2 a v3

Guida alla migrazione da v2 a v3

Questo documento ti aiuta a migrare il codice esistente da Tripo API v2 a v3.

Passa da V2 a V3 con lo Skill

Non devi prima capire tutte le differenze tra le API. Scarica questo Skill, inserisci il file nella directory del progetto da migrare e chiedi al tuo strumento di programmazione basato sull’IA di usarlo. Ti aiuterà a trovare le chiamate V2 nel tuo progetto e a migrarle a V3 passo dopo passo.

Passaggio 1: Scarica lo Skill

Scarica

Otterrai un file chiamato SKILL.md. Non modificare il nome del file.

Passaggio 2: Inserisci lo Skill nella directory del progetto e usalo

Inserisci il file SKILL.md scaricato nella directory del progetto da migrare. Poi apri il progetto e chiedi direttamente all’IA di usare questo Skill.

Passaggio 3: Copia questo messaggio per avviare la migrazione

Apri il progetto che vuoi migrare. Copia il messaggio completo qui sotto e invialo al tuo strumento di programmazione basato sull’IA:

Usa il file `SKILL.md` nella directory del progetto per migrare l'integrazione Tripo API di questo progetto da V2 a V3. Prima mostrami cosa deve cambiare. Attendi la mia conferma, quindi applica le modifiche. Infine, usa la checklist contenuta nel file per assicurarti che non sia stato tralasciato nulla.

Lo strumento troverà prima le chiamate V2 e ti mostrerà un piano, così non dovrai cercare in ogni file.

Grandi cambiamenti

1. Modifica base URL

# v2
https://api.tripo3d.ai/v2/openapi/

# v3
https://openapi.tripo3d.ai/v3/

2. Endpoint universale suddiviso in endpoint dedicati

v2 utilizza un singolo endpoint POST /v2/openapi/task e un campo type per distinguere i tipi di attività. v3 fornisce un endpoint dedicato per ciascuna funzionalità, quindi il campo type non è più obbligatorio.

JSON
// v2
POST /v2/openapi/task
{ "type": "text_to_model", "prompt": "a cat" }

// v3
POST /v3/generation/text-to-model
{ "prompt": "a cat", "model": "v3.1-20260211" }

3. Ingressi file unificati come campo input

In v2, vengono utilizzati nomi di campo diversi a seconda della sorgente di input, come file, file_token, url e object. In v3, sono unificati nel campo input e il sistema deduce automaticamente il tipo di input.

JSON
// v2 - different field names are required
{ "type": "refine_model", "draft_model_task_id": "123e4567-e89b-42d3-a456-426614174000" }
{ "type": "convert_model", "original_model_task_id": "123e4567-e89b-42d3-a456-426614174000" }

// v3 - use input consistently
{ "input": "123e4567-e89b-42d3-a456-426614174000" }
{ "input": "https://example.com/model.glb" }
{ "input": "file_token_abc123" }

4. Nomi di campo standardizzati

Campo v2 Campo v3
create_time created_at
consumed_credit credits_consumed

5. Divisione testo-immagine e immagine-immagine

In v2, testo-immagine e immagine-immagine condividono lo stesso API. In v3, sono suddivisi in endpoint dedicati:

  • POST /v3/generation/text-to-image - Genera un’immagine da input di solo testo
  • POST /v3/generation/image-to-image - Genera o modifica un’immagine basata su un’immagine di riferimento

Mappatura degli endpoint

Generazione

Tipo v2 Valore Punto finale v3
text_to_model POST /v3/generation/text-to-model
image_to_model POST /v3/generation/image-to-model
multiview_to_model POST /v3/generation/multiview-to-model
text_to_image POST /v3/generation/text-to-image
generate_image POST /v3/generation/image-to-image
generate_multiview_image POST /v3/generation/image-to-multiview
edit_multiview_image POST /v3/generation/edit-multiview

Elaborazione del modello

Tipo v2 Valore Punto finale v3
refine_model POST /v3/models/refine
convert_model POST /v3/models/convert
import_model POST /v3/models/import
stylize_model POST /v3/models/stylize
texture_model POST /v3/models/texture

Animazione

Tipo v2 Valore Punto finale v3
animate_prerigcheck POST /v3/animations/rig-check
animate_rig POST /v3/animations/rig
animate_retarget POST /v3/animations/retarget

Modifica della mesh

Tipo v2 Valore Punto finale v3
mesh_segmentation POST /v3/mesh/segment
mesh_completion POST /v3/mesh/complete
highpoly_to_lowpoly POST /v3/mesh/decimate

Attività e file

Punto finale v2 Punto finale v3
GET /v2/openapi/task/{task_id} GET /v3/tasks/{task_id}
POST /v2/openapi/upload POST /v3/files

Passaggi di migrazione

Passaggio 1: aggiorna la base URL

Python
# v2
BASE_URL = "https://api.tripo3d.ai/v2/openapi"

# v3
BASE_URL = "https://openapi.tripo3d.ai/v3"

Passaggio 2: sostituire gli endpoint utilizzando la tabella di mappatura

Python
# v2
response = requests.post(f"{BASE_URL}/task", json={
    "type": "text_to_model",
    "prompt": "a cat"
})

# v3
response = requests.post(f"{BASE_URL}/generation/text-to-model", json={
    "prompt": "a cat",
    "model": "v3.1-20260211"
})

Passaggio 3: rimuovere il campo type

In v3, il percorso dell’endpoint implica già il tipo di attività, quindi il corpo della richiesta non necessita più del campo type.

Passaggio 4: sostituisci i campi di input con input

Python
# v2 - different task types use different field names
payload = {"type": "refine_model", "draft_model_task_id": "123e4567-e89b-42d3-a456-426614174000"}
payload = {"type": "convert_model", "original_model_task_id": "123e4567-e89b-42d3-a456-426614174000"}

# v3 - use input consistently
payload = {"input": "123e4567-e89b-42d3-a456-426614174000"}

Passaggio 5: aggiornare i nomi dei campi di risposta

Python
# v2
created = task["create_time"]
cost = task["consumed_credit"]

# v3
created = task["created_at"]
cost = task["credits_consumed"]

Passaggio 6: testare e convalidare

  1. Sostituisci e testa ciascun endpoint uno alla volta
  2. Verificare che la creazione delle attività e il polling funzionino correttamente
  3. Confermare che i collegamenti per il download siano disponibili
  4. Verificare che le query sulla detrazione del credito e sul saldo funzionino correttamente

Note

  • v2 e v3 possono funzionare in parallelo. Ti consigliamo di eseguire la migrazione gradualmente invece di effettuare il passaggio tutto in una volta
  • API Keys sono condivisi tra v2 e v3. Non è necessario creare nuove chiavi
  • Usa l’ID restituito dalla creazione di ogni attività. Verifica la compatibilità prima di interrogare tramite v3 un’attività v2 esistente.
PrecedenteWebhooksAvantiImporta modello