Richieste

Una richiesta è una chiamata a un modello. Ha un id (req_…), uno stato, il relativo costo in crediti API (1000 = 1 USD) e, quando va a buon fine, i file generati. Lo stesso oggetto viene restituito da ogni endpoint qui sotto, per ogni modello.

Trovare un modello#

Il catalogo di tutti i 1496 modelli è un JSON pubblico (non serve una chiave):

curl "https://api.doitong.com/v1/models?category=text-to-video&lab=Google&limit=20"

Ogni riga contiene id, name, lab, category, family, summary, tags, output_kind, docs_url e un oggetto price (vedi Prezzi). GET https://api.doitong.com/v1/models/{model_id} aggiunge lo JSON Schema completo dell'input e dell'output, i nomi canonici dei parametri, le regole di prezzo e un esempio di input. Una category o un mode sconosciuti restituiscono 400 invalid_parameter.

Eseguire un modello#

curl -X POST "https://api.doitong.com/v1/run/{model_id}?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1842-cover" \
  -d '{"prompt": "..."}'

• Il corpo è l'input del modello, un oggetto JSON. Ogni pagina del modello elenca i relativi parametri.
• L'input viene verificato prima di qualsiasi addebito. Un input non valido restituisce 422 invalid_input con il param responsabile e non costa nulla.
• ?wait=N (fino a 20 secondi) mantiene la chiamata in attesa finché la richiesta non termina o il tempo non scade.
• ?webhook_url=https://… invia un POST firmato a quell'URL quando la richiesta termina (vedi Webhook).
• ?storage=permanent o ?storage=temporary sceglie per quanto tempo conservare i file di output; senza questo parametro si applica l'impostazione dell'account (vedi Dove vengono conservati i file).

La risposta è 202 Accepted mentre la richiesta è ancora in esecuzione e 200 OK quando è terminata entro il tempo di attesa (o quando è una riproduzione, vedi sotto). Gli header Location e Doitong-Request-Id contengono l'URL e l'id della richiesta.

Stati#

Una richiesta che supera il limite di tempo termina con il codice timeout e viene rimborsata: 15 minuti per le immagini, 60 minuti per i video, 30 minuti per l'audio e tutto il resto.

L'oggetto richiesta#

{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "flux/schnell",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:01Z",
  "completed_at": "2026-10-20T12:00:02Z",
  "queue_position": null,
  "cost": { "credits": 3, "usd": "0.003", "charged": 3, "refunded": 0 },
  "input": { "prompt": "..." },
  "output": { "images": [ { "url": "https://content.doitong.com/dev-api/…/0-output.jpeg", "width": 1024, "height": 768 } ] },
  "outputs": [
    { "type": "image", "url": "https://content.doitong.com/dev-api/…/0-output.jpeg", "content_type": "image/jpeg",
      "width": 1024, "height": 768, "file_size": 183920, "stored": true }
  ],
  "error": null,
  "metrics": { "inference_seconds": 1.2 },
  "storage": { "mode": "permanent", "bytes": 183920, "expires_at": null, "expired": false },
  "urls": {
    "self": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}

• outputs è uguale per ogni modello: una voce per ogni file generato con type (image, video, audio, file o 3d), un url sulla nostra archiviazione, content_type e, quando noti, file_size, width, height, duration.
• output è l'oggetto risultato del modello (i relativi campi sono elencati in ogni pagina del modello) con gli stessi URL.
• storage indica come vengono conservati i file: mode (permanent o temporary), bytes archiviati, expires_at (quando un file temporaneo viene eliminato, null per quelli permanenti) e expired (true una volta eliminati i file).
• cost.credits è il prezzo della chiamata in crediti API (cost.usd in USD), cost.charged è quanto è stato addebitato dal saldo API, cost.refunded è quanto è stato restituito. Per un modello metered, cost.credits è il massimo trattenuto all'inizio (cost.held); quando l'esecuzione va a buon fine, cost.settled indica il costo effettivo dell'utilizzo e il resto del massimo è in cost.refunded (vedi Addebito in base all'utilizzo).
• Quando una richiesta non va a buon fine, error è { "type": …, "code": …, "message": … }.

Leggere una richiesta#

curl "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

• ?wait=N (fino a 20 secondi) esegue un long polling: la chiamata restituisce il risultato non appena la richiesta è finale oppure dopo N secondi con lo stato corrente. Ripetere questa chiamata è il modo più semplice per attendere un risultato.
• ?logs=1 aggiunge le righe del log di avanzamento del modello (le ultime 50) come logs.

Puoi leggere solo le richieste del tuo account; qualsiasi altro id restituisce 404 request_not_found.

Elencare le richieste#

curl "https://api.doitong.com/v1/requests?limit=20&status=succeeded&model=flux/schnell" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

Dalla più recente alla meno recente. limit va da 1 a 100 (predefinito 20), mentre status e model filtrano i risultati. La risposta è { "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }; passa cursor=<next_cursor> per la pagina successiva.

Annullare una richiesta#

curl -X POST "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

• Annullata prima dell'avvio del modello: lo stato diventa canceled, i crediti API vengono rimborsati e ricevi 200.
• Già in fase di generazione: l'annullamento viene inoltrato e ricevi 202 con "cancel_requested": true. Se il modello termina comunque, la richiesta va a buon fine normalmente e viene addebitata.
• Già finale: 409 not_cancelable (una richiesta già canceled restituisce semplicemente 200).

Eliminare i file di una richiesta#

curl -X DELETE "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/files" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

Elimina subito le nostre copie dei file di output della richiesta e interrompe il relativo addebito di archiviazione. La risposta è l'oggetto richiesta con storage.expired: true; gli URL restano nel record ma non funzionano più. Chiamare di nuovo l'endpoint non cambia nulla (200). Una richiesta ancora queued o running non ha file: 409 request_active. Richiede models:run.

Idempotenza: riprovare senza pagare due volte#

Le reti possono interrompersi. Per riprovare un'esecuzione in sicurezza, invia un header Idempotency-Key (una stringa qualsiasi di massimo 255 caratteri, univoca per operazione, ad esempio il tuo id dell'ordine):

• Stessa chiave e stesso corpo di prima: ricevi di nuovo la richiesta originale (200, header Idempotent-Replayed: true) e non viene effettuato un nuovo addebito.
• Stessa chiave e corpo dopo un'esecuzione non riuscita prima di raggiungere il modello (upstream_error o internal_error all'invio, insufficient_credits, budget_exceeded, too_many_inflight): non è stato prodotto nulla e non è stato addebitato nulla, quindi il nuovo tentativo esegue di nuovo il modello invece di restituire l'errore.
• Stessa chiave con un corpo diverso: 409 idempotency_mismatch.
• Le chiavi sono associate alla chiave API che le ha inviate.

Dove vengono conservati i file#

Ogni file di output viene copiato nella nostra archiviazione prima che la richiesta venga contrassegnata come succeeded, quindi gli URL in outputs si trovano sui nostri host e puoi collegarti direttamente a essi. La durata di conservazione dipende da te:

• L'impostazione dell'account decide il comportamento per le nuove richieste: l'interruttore "Conserva i file per sempre" nella dashboard oppure PATCH https://api.doitong.com/v1/account/storage con {"mode": "temporary"}. GET https://api.doitong.com/v1/account la mostra sotto storage, insieme ai byte conservati e alla stima mensile.
• ?storage=permanent|temporary durante un'esecuzione (l'argomento storage dello strumento MCP run) sostituisce l'impostazione per quella esecuzione.
• Modificare l'impostazione non tocca mai i file già presenti; eliminali con DELETE /requests/{id}/files.
• Quando il saldo API non può pagare l'archiviazione, non viene addebitato nulla e ricevi un'email: effettua una ricarica entro 30 giorni, altrimenti i file conservati diventano temporanei e vengono eliminati 7 giorni dopo.

Nel raro caso in cui la nostra copia non riesca, la voce contiene "stored": false e l'URL è quello originale, con durata limitata: downloadalo presto.