Replica Link API

Replica Link integra un server HTTP all'interno dell'app Replica Pro per macOS, esponendo un'API REST sulla rete locale. Tutti gli endpoint restituiscono JSON salvo diversa indicazione.

• Base URL: http://<ip-locale>:8247
• Protocollo: HTTP (TLS disponibile ma disabilitato di default)
• Autenticazione: basata su PIN, con Bearer token per le richieste successive

---

Guida Rapida

# 1. Autenticazione
TOKEN=$(curl -s -X POST http://192.168.1.10:8247/api/auth \
  -H "Content-Type: application/json" \
  -d '{"pin":"482193"}' | jq -r '.token')

# 2. Lista progetti
curl -s http://192.168.1.10:8247/api/projects \
  -H "Authorization: Bearer $TOKEN" | jq

# 3. Carica un nuovo progetto
curl -s -X POST http://192.168.1.10:8247/api/projects \
  -H "Authorization: Bearer $TOKEN" \
  -F "name=TestProject" \
  -F "images=@photo1.jpg" \
  -F "images=@photo2.jpg" | jq

# 4. Avvia elaborazione
curl -s -X POST http://192.168.1.10:8247/api/projects/<project-id>/compute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"detail":"medium"}' | jq

# 5. Polling stato
curl -s http://192.168.1.10:8247/api/status \
  -H "Authorization: Bearer $TOKEN" | jq

# 6. Scarica modello
curl -s -o model.glb \
  http://192.168.1.10:8247/api/projects/<project-id>/download?format=glb \
  -H "Authorization: Bearer $TOKEN"

---

Autenticazione

Tutti gli endpoint tranne POST /api/auth e GET /api/health richiedono autenticazione tramite:

• Header: Authorization: Bearer <token>
• Parametro query: ?token=<token> (per contesti dove non è possibile impostare header, es. <model-viewer>)

I token scadono dopo 24 ore.

Health Check

Endpoint di verifica stato. Non richiede autenticazione.

Risposta 200

{
  "status": "ok",
  "version": "1.0"
}

Autenticazione

Autenticati con il PIN a 6 cifre mostrato nell'app Replica desktop.

Corpo Richiesta

{
  "pin": "482193"
}

Risposta 200

{
  "token": "550e8400-e29b-41d4-a716-446655440000"
}

Errori

Stato	Corpo	Causa
400	{"error": "Invalid request body"}	JSON malformato
401	{"error": "Invalid PIN"}	PIN errato

---

Progetti

Lista Progetti

Restituisce tutti i progetti.

Risposta 200

{
  "projects": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "MyProject",
      "imageCount": 42,
      "status": "completed",
      "progress": 1.0,
      "processingStage": "",
      "hasModel": true,
      "hasGlb": true,
      "modelDetail": "medium",
      "errorMessage": ""
    }
  ]
}

Dettaglio Progetto

Ottieni i dettagli di un singolo progetto.

Parametri Path

Parametro	Tipo	Descrizione
id	stringa UUID	ID persistente del progetto

Risposta 200 — Stessa struttura di un singolo elemento nella lista progetti.

Errori

Stato	Causa
404	Progetto non trovato

Crea Progetto

Crea un nuovo progetto caricando immagini.

Content-Type: multipart/form-data

Campi del Form

Campo	Tipo	Obbligatorio	Descrizione
name	string	No	Nome del progetto. Default: LinkUpload_<timestamp>
images	file[]	Sì	Una o più immagini

Formati immagine supportati: jpg, jpeg, png, heif, heifs, raw, tif, tiff

Risposta 201

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "MyProject",
  "imageCount": 42,
  "status": "ready"
}

Errori

Stato	Causa
400	Nessuna immagine fornita, formato non supportato, o content type non valido
412	Cartella di upload non configurata nell'app desktop
500	Impossibile creare la cartella del progetto

Rinomina Progetto

Rinomina un progetto. Rinomina sia il progetto che la sua cartella su disco.

Corpo Richiesta

{
  "name": "NewProjectName"
}

Regole di validazione:

• Il nome non può essere vuoto
• Il nome non può contenere / o \
• Non è possibile rinominare un progetto in elaborazione o in coda
• La cartella di destinazione non deve già esistere

Risposta 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "NewProjectName"
}

Errori

Stato	Causa
400	Nome vuoto, separatori di percorso, già in elaborazione, o conflitto cartella
404	Progetto non trovato

Elimina Progetto

Elimina un progetto. Opzionalmente rimuove i file dal disco.

Parametri Query

Parametro	Tipo	Default	Descrizione
deleteFiles	string	"false"	Imposta a "true" per eliminare anche la cartella del progetto dal disco

Risposta 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "deleted": true
}

Errori

Stato	Causa
404	Progetto non trovato

---

Immagini

Aggiungi Immagini

Aggiungi immagini a un progetto esistente.

Content-Type: multipart/form-data

Campi del Form

Campo	Tipo	Obbligatorio	Descrizione
images	file[]	Sì	Una o più immagini

Risposta 200

{
  "imageCount": 58,
  "addedCount": 16
}

Campo	Descrizione
imageCount	Conteggio totale immagini dopo l'aggiunta
addedCount	Numero di immagini aggiunte con successo

Errori

Stato	Causa
400	Nessuna immagine fornita o content type non valido
404	Progetto non trovato

Miniatura Immagine

Serve una singola immagine come miniatura JPEG.

• Dimensione massima: 400px (lato più lungo)
• Formato: JPEG, qualità 0.7
• Content-Type: image/jpeg

Errori

Stato	Causa
404	Progetto o immagine non trovati
500	Impossibile generare la miniatura

Scarica Tutte le Immagini

Scarica tutte le immagini del progetto come archivio ZIP.

• Content-Type: application/zip
• Content-Disposition: attachment; filename="<nome-progetto>_images.zip"

Errori

Stato	Causa
400	Il progetto non ha immagini
404	Progetto non trovato
500	Impossibile creare l'archivio ZIP

---

Elaborazione

Avvia Elaborazione

Avvia l'elaborazione fotogrammetrica su un progetto.

Precondizioni:

• Lo stato del progetto deve essere ready o completed
• Il progetto deve avere almeno un'immagine

Corpo Richiesta (tutti i campi opzionali — default: dettaglio medium)

{
  "detail": "medium",
  "sampleOrdering": "unordered",
  "featureSensitivity": "normal",
  "meshPrimitive": "triangle",
  "isObjectMaskingEnabled": false
}

Parametri Standard

Campo	Valori	Default	Descrizione
detail	preview, reduced, medium, full, raw, custom	medium	Livello di dettaglio ricostruzione
sampleOrdering	unordered, sequential	unordered	Suggerimento ordine di cattura foto
featureSensitivity	normal, high	normal	Sensibilità rilevamento feature
meshPrimitive	triangle, quad	triangle	Tipo primitiva mesh di output
isObjectMaskingEnabled	true, false	false	Mascheramento automatico oggetto

Parametri Custom (solo quando detail è "custom")

Campo	Tipo	Descrizione
maximumPolygonCount	int	Conteggio massimo poligoni
maximumTextureDimension	string	oneK, twoK, fourK, eightK, sixteenK
textureFormat	string	png, jpeg
jpegCompressionQuality	float	0.0 – 1.0 (solo con formato jpeg)
outputTextureMaps	string[]	["all"] o sottoinsieme: ambientOcclusion, diffuseColor, displacement, normal, roughness

Risposta 202

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

Errori

Stato	Causa
404	Progetto non trovato
409	Il progetto è già in elaborazione o in coda

Annulla Elaborazione

Annulla un'elaborazione in corso o in coda.

Precondizioni: Lo stato del progetto deve essere processing o queued.

Risposta 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "ready"
}

Errori

Stato	Causa
404	Progetto non trovato o non in elaborazione

---

Modelli 3D

Servi Modello

Serve il modello GLB per l'uso con <model-viewer> o visualizzatori 3D simili.

• Content-Type: model/gltf-binary

Errori

Stato	Causa
404	Modello GLB non disponibile

Servi Modello (Viewer)

Come sopra, ma accetta l'autenticazione tramite parametro query invece che header. Progettato per <model-viewer> che non può inviare header personalizzati.

Parametri Query

Parametro	Obbligatorio	Descrizione
token	Sì	Token di sessione

Nota: Questo endpoint NON passa attraverso il middleware di autenticazione — valida il token inline.

Scarica Modello

Scarica il modello 3D nel formato richiesto. La conversione viene eseguita su richiesta e memorizzata in cache.

Parametri Query

Parametro	Valori	Default	Descrizione
format	glb, usdz, obj, fbx	glb	Formato di output

Content Type

Formato	Content-Type
glb	model/gltf-binary
usdz	model/vnd.usdz+zip
obj	text/plain
fbx	application/octet-stream

Comportamento:

• USDZ è il formato di output nativo — servito direttamente, nessuna conversione necessaria
• GLB viene generato automaticamente durante i workflow Link e memorizzato in cache in link-exports/
• OBJ e FBX vengono generati su richiesta tramite Blender e memorizzati in cache per le richieste successive

Errori

Stato	Causa
400	Formato non valido
404	Progetto o modello non trovato
500	Conversione fallita

---

Stato e Polling

Polling Stato

Endpoint di polling leggero. Restituisce lo stato minimo di tutti i progetti più un intervallo di polling adattivo.

Risposta 200

{
  "projects": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "processing",
      "progress": 0.63,
      "processingStage": "Mesh Generation",
      "hasGlb": false,
      "errorMessage": ""
    }
  ],
  "pollInterval": 2
}

Campo	Descrizione
pollInterval	Intervallo di polling suggerito in secondi: 2 se un progetto è in elaborazione/coda, 10 altrimenti

---

Modelli Dati

Stato Progetto

Valore	Descrizione
ready	Immagini caricate, pronto per l'elaborazione
queued	In attesa nella coda di elaborazione
processing	Fotogrammetria in corso
completed	Modello generato con successo
failed	Elaborazione fallita (vedi errorMessage)

LinkProjectDTO (Completo)

id              string    UUID
name            string    Nome cartella progetto
imageCount      int       Numero di immagini
status          string    Stato del progetto
progress        double    0.0 – 1.0
processingStage string    Fase corrente (es. "Mesh Generation")
hasModel        bool      Esiste il modello USDZ
hasGlb          bool      Esiste l'export GLB
modelDetail     string    Livello di dettaglio usato
errorMessage    string    Descrizione errore (vuota se nessuno)

LinkStatusProjectDTO (Leggero)

id              string    UUID
status          string    Stato del progetto
progress        double    0.0 – 1.0
processingStage string    Fase corrente
hasGlb          bool      Esiste l'export GLB
errorMessage    string    Descrizione errore

---

Gestione Errori

Tutti gli errori restituiscono un corpo JSON:

{
  "error": "Messaggio di errore descrittivo"
}

Codici di Stato HTTP

Codice	Utilizzo
200	Successo
201	Risorsa creata (upload progetto)
202	Accettato (elaborazione in coda)
400	Richiesta non valida (validazione, corpo malformato)
401	Non autorizzato (token o PIN non valido/mancante)
404	Risorsa non trovata
409	Conflitto (progetto già in elaborazione)
412	Precondizione fallita (cartella di upload non configurata)
500	Errore interno del server (I/O file, fallimento conversione)

---

Configurazione Server

Parametro	Default	Note
Porta	8247	Fallback su 8248+ se in uso
Protocollo	HTTP	TLS disponibile ma disabilitato di default
Scadenza sessione	24 ore	Automatica
Lunghezza PIN	6 cifre	Rigenerabile dall'interfaccia desktop