API di Studii

Richiama qualsiasi strumento di Studii dal tuo server, script o prodotto. Piano Pro e superiori.

Autenticazione

Emetti una chiave su /app/settings/api-keys. Inviala a ogni richiesta come token Bearer (o tramite x-api-key):

Authorization: Bearer stu_<your-key>

Creare un lavoro

Invia una generazione. Restituisce subito l'ID del lavoro; interrogastatus_urlfinché lo stato non è completed o failed.

POST https://studii.tech/api/v1/jobs
Authorization: Bearer stu_<your-key>
Content-Type: application/json

{
  "tool": "studio",
  "inputs": {
    "mode": "image",
    "source": "text",
    "quality": "standard",
    "aspect_ratio": "16:9",
    "prompt": "A misty pine forest at dawn, shafts of golden light"
  }
}

Risposta 202:

{
  "id": "8a1f...",
  "status": "queued",
  "status_url": "https://studii.tech/api/v1/jobs/8a1f...",
  "credits_charged": 8
}

Interrogare lo stato

GET https://studii.tech/api/v1/jobs/<id>
Authorization: Bearer stu_<your-key>

Risposta 200:

{
  "id": "8a1f...",
  "status": "completed",
  "output_url": "https://...supabase.co/.../outputs/<key>",
  "output_kind": "image",
  "tool": "studio",
  "error": null,
  "created_at": "2026-05-14T...",
  "completed_at": "2026-05-14T...",
  "credits_charged": 8
}

Caricare un'immagine sorgente

Gli strumenti immagine-a-immagine (virtual-staging, photo-restore, product-background, career-photo) richiedono un'immagine sorgente. Flusso in due passaggi:

Passaggio 1 — richiedi un URL firmato:

POST https://studii.tech/api/v1/uploads
Authorization: Bearer stu_<your-key>
Content-Type: application/json

{
  "filename": "kitchen.jpg",
  "content_type": "image/jpeg"
}

Risposta 200:

{
  "object_key": "8a1f.../9c3e....jpg",
  "signed_url": "https://...supabase.co/storage/v1/...?token=...",
  "token": "...",
  "expires_in": 7200
}

Passaggio 2 — invia i byte con PUT (nessun header di autenticazione, il content-type deve corrispondere):

curl -X PUT "$SIGNED_URL" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@kitchen.jpg"

Passaggio 3 — invia il lavoro con source_object_key impostato sull'object_key restituito:

POST https://studii.tech/api/v1/jobs
Authorization: Bearer stu_<your-key>
Content-Type: application/json

{
  "tool": "virtual-staging",
  "inputs": { "style": "modern", "room": "living" },
  "source_object_key": "8a1f.../9c3e....jpg"
}

Slug degli strumenti

• studio — generazione di testo o immagine-a-immagine / video
• virtual-staging — richiede source_object_key
• photo-restore — richiede source_object_key
• product-background — richiede source_object_key
• career-photo — richiede source_object_key (un ritratto frontale)

Errori

Limiti di spesa

Ogni chiave può avere un limite di crediti. Quando il limite viene raggiunto, i lavori restituiscono 402. I limiti sono indicativi — non rimborsano a lavoro in corso. Usa un limite basso sulle chiavi di produzione per contenere costi incontrollati.

Limiti di frequenza

Pro: 60 richieste/min per chiave. Team e Business: 300/min. Aumentabile tramite l'assistenza, se necessario.