Riferimento API

Riferimento REST API: invia, controlla e annulla generazioni; consulta modelli e prezzi, richiedi preventivi, controlla il saldo e carica immagini, video e audio, con esempi.

L’API si basa su alcune risorse: generations (le attività che avvii), modelli (cosa puoi eseguire e quanto costa), quotes, account e uploads. Tutte le richieste e le risposte usano JSON su HTTPS.

URL di basehttps://cheapergen.com/api/v1

Autenticati con Authorization: Bearer cg_live_… (vedi Autenticazione). Gli errori seguono il formato descritto in Errori. Tutti gli endpoint inviano header CORS; non esporre la tua chiave nel browser: solo gli endpoint pubblici sono pensati per essere chiamati lato client.

Endpoint API
Endpoint	Descrizione
POST/run/{endpoint}	Invia una generazione
GET/generations/{id}	Recupera una generazione
GET/generations	Elenca le generazioni
POST/generations/{id}/cancel	Annulla una generazione in coda
DELETE/generations/{id}	Elimina una generazione e i relativi contenuti multimediali
GET/models	Elenca modelli e prezzi
GET/models/{vendor}/{model}	Recupera un modello con gli schemi di input
POST/quote/{endpoint}	Calcola il prezzo di un input
GET/account	Saldo, credito per immagini e ricarica automatica
GET/account/pricing	Il tuo piano e i tuoi prezzi personalizzati
POST/uploads	Carica un'immagine, un video o un file audio di input
GET/webhooks/secret	Il tuo segreto di firma dei webhook

Invia una generazione#

POST/api/v1/run/{endpoint}Chiave API richiesta

Avvia una generazione asincrona e restituisce 202 Accepted con un oggetto di generazione nello stato queued. A questo punto l’importo viene trattenuto dal saldo (vedi Fatturazione).

Parametri del percorso

endpointstringobbligatorio: L’ID endpoint del modello, {vendor}/{model}/{task}; per esempio bytedance/seedance-2.0-fast/text-to-video. Trovi tutti gli ID nella pagina Modelli.

Corpo

…model inputsobjectobbligatorio: I campi di input dell’endpoint, come prompt, resolution o image_url. I campi, i tipi, i valori predefiniti e quelli consentiti per ogni modello sono descritti nella relativa pagina API e restituiti in JSON Schema da Recupera un modello. I campi sconosciuti vengono rifiutati.
webhook_urlstring (https URL): Facoltativo. Inviamo con POST la generazione completata a questo URL. Vedi Webhook.
retentionstring: Facoltativo. Per quanto tempo conserviamo prompt, input e output della generazione: immediate, 1h, 1d, 7d o 30d. Per impostazione predefinita si usa il valore del tuo account (1d). Qualsiasi account può ridurre il periodo di conservazione; 7d e 30d richiedono un’impostazione Enterprise. Vedi Conservazione dei dati.
allow_fallback_priceboolean: Opzionale, predefinito true. Quando la capacità abituale non è disponibile per questa richiesta, eseguila su una capacità più costosa applicando il prezzo di emergenza — al massimo al prezzo ufficiale del modello e mai oltre max_cost_usd. Si applica all'invio (il prezzo compare nella risposta e in /quote) e, se la capacità non è disponibile dopo l'accettazione del lavoro, a un eventuale passaggio successivo (in quel momento viene trattenuto l'importo aggiuntivo; pricing.fallback e i webhook lo indicano). Imposta false per non pagare mai più del prezzo comunicato: nei piani Pro o Max, altrimenti un lavoro accettato potrebbe passare a una capacità più costosa, al massimo al prezzo standard. In tal caso riceverai 503 fallback_price_declined invece di un prezzo più alto, oppure il lavoro non riuscirà e verrà rimborsato.
max_cost_usdnumber: Facoltativo. L’importo massimo che accetti di pagare per questa generazione, prezzo di emergenza incluso. Se viene superato, ricevi 400 max_cost_exceeded e non ti viene addebitato nulla; il prezzo non verrà aumentato nemmeno in seguito.

const resp = await fetch("https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/text-to-video", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CHEAPERGEN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "prompt": "Lento avvicinamento a un ceramista che modella un vaso all’ora dorata, polvere sospesa nella luce, profondità di campo ridotta",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5
  }),
});
const generation = await resp.json();

import os, requests

resp = requests.post(
    "https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/text-to-video",
    headers={"Authorization": f"Bearer {os.environ['CHEAPERGEN_API_KEY']}"},
    json={
        "prompt": "Lento avvicinamento a un ceramista che modella un vaso all’ora dorata, polvere sospesa nella luce, profondità di campo ridotta",
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "duration": 5
    },
)
generation = resp.json()

curl -X POST https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/text-to-video \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Lento avvicinamento a un ceramista che modella un vaso all’ora dorata, polvere sospesa nella luce, profondità di campo ridotta",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}'

Risposta · 202 Accepted

{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "object": "generation",
  "model": "bytedance/seedance-2.0-fast",
  "endpoint": "bytedance/seedance-2.0-fast/text-to-video",
  "mode": "text-to-video",
  "status": "queued",
  "input": {
    "prompt": "Lento avvicinamento a un ceramista che modella un vaso all’ora dorata, polvere sospesa nella luce, profondità di campo ridotta",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": true
  },
  "output": null,
  "error": null,
  "cost": {
    "amount_usd": 0.4494,
    "currency": "usd",
    "estimated": true
  },
  "source": "api",
  "created_at": "2026-10-15T09:21:04.512Z",
  "started_at": null,
  "completed_at": null,
  "retention": "1d",
  "expires_at": null,
  "purged_at": null,
  "urls": {
    "get": "https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z",
    "cancel": "https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z/cancel"
  }
}

Errori: 400 invalid_request (validazione), 401 unauthorized, 402 insufficient_balance, 404 not_found (endpoint sconosciuto), 429 rate_limited (frequenza delle richieste, oppure la tua coda di generazioni in attesa è piena), 503 model_unavailable, 503 pricing_unavailable (riprova tra qualche secondo; non è stato addebitato nulla), 503 fallback_price_declined (è disponibile solo il prezzo di emergenza e hai inviato allow_fallback_price: false), 400 max_cost_exceeded.

Recupera una generazione#

GET/api/v1/generations/{id}Chiave API richiesta

Restituisce la generazione tramite ID. Se è previsto un controllo di stato, lo esegue prima di rispondere: per portare un’attività a termine basta quindi interrogare questo endpoint. Restituisce 404 not_found per gli ID sconosciuti e per le generazioni appartenenti a un altro account.

Richiesta

curl https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Risposta · 200 OK

{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "object": "generation",
  "model": "bytedance/seedance-2.0-fast",
  "endpoint": "bytedance/seedance-2.0-fast/text-to-video",
  "mode": "text-to-video",
  "status": "succeeded",
  "input": {
    "prompt": "Lento avvicinamento a un ceramista che modella un vaso all’ora dorata, polvere sospesa nella luce, profondità di campo ridotta",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": true
  },
  "output": {
    "video": {
      "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.mp4",
      "content_type": "video/mp4"
    }
  },
  "error": null,
  "cost": {
    "amount_usd": 0.4494,
    "currency": "usd",
    "estimated": false
  },
  "source": "api",
  "created_at": "2026-10-15T09:21:04.512Z",
  "started_at": "2026-10-15T09:21:09.031Z",
  "completed_at": "2026-10-15T09:22:31.870Z",
  "retention": "1d",
  "expires_at": "2026-10-16T09:22:31.870Z",
  "purged_at": null
}

Elenca le generazioni#

GET/api/v1/generationsChiave API richiesta

Elenca le tue generazioni, dalla più recente. Include i job inviati da Studio e dagli ambienti di prova.

Parametri di query

limitinteger: Dimensione della pagina, da 1 a 100. Valore predefinito: 20.
cursorstring: Il next_cursor della pagina precedente.
statusstring: Restituisce solo le generazioni con stato: queued, running, succeeded, failed o canceled.
modelstring: Restituisce solo le generazioni per questo ID modello, per esempio bytedance/seedance-2.0-fast.
sourcestring: Restituisce solo le generazioni avviate da playground (Studio e pagine dei modelli), api o mcp (agenti AI).

Richiesta

curl "https://cheapergen.com/api/v1/generations?limit=2&status=succeeded" \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Risposta · 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "gen_8c2QmX1nq0k4Lw7Z",
      "object": "generation",
      "model": "bytedance/seedance-2.0-fast",
      "endpoint": "bytedance/seedance-2.0-fast/text-to-video",
      "mode": "text-to-video",
      "status": "succeeded",
      "input": {
        "prompt": "Lento avvicinamento a un ceramista che modella un vaso all’ora dorata, polvere sospesa nella luce, profondità di campo ridotta",
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "duration": 5,
        "generate_audio": true
      },
      "output": {
        "video": {
          "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.mp4",
          "content_type": "video/mp4"
        }
      },
      "error": null,
      "cost": {
        "amount_usd": 0.4494,
        "currency": "usd",
        "estimated": false
      },
      "source": "api",
      "created_at": "2026-10-15T09:21:04.512Z",
      "started_at": "2026-10-15T09:21:09.031Z",
      "completed_at": "2026-10-15T09:22:31.870Z",
      "retention": "1d",
      "expires_at": "2026-10-16T09:22:31.870Z",
      "purged_at": null
    },
    {
      "id": "gen_3vYk2PqL9sTn0bWd",
      "object": "generation",
      "model": "bytedance/seedream-5.0-pro",
      "endpoint": "bytedance/seedream-5.0-pro/text-to-image",
      "mode": "text-to-image",
      "status": "succeeded",
      "input": {
        "prompt": "Foto editoriale di una macchina per espresso nera opaca su travertino, luce soffusa dalla finestra, 85 mm",
        "aspect_ratio": "1:1",
        "size": "2K"
      },
      "output": {
        "images": [
          {
            "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.png",
            "content_type": "image/png"
          }
        ]
      },
      "error": null,
      "cost": {
        "amount_usd": 0.0665,
        "currency": "usd",
        "estimated": false
      },
      "source": "api",
      "created_at": "2026-10-15T09:21:04.512Z",
      "started_at": "2026-10-15T09:21:09.031Z",
      "completed_at": "2026-10-15T09:22:31.870Z",
      "retention": "1d",
      "expires_at": "2026-10-16T09:22:31.870Z",
      "purged_at": null
    }
  ],
  "next_cursor": "gen_3vYk2PqL9sTn0bWd"
}

next_cursor è null nell’ultima pagina.

Annulla una generazione#

POST/api/v1/generations/{id}/cancelChiave API richiesta

Annulla una generazione ancora nello stato queued e rimborsa per intero l’importo trattenuto. Restituisce la generazione aggiornata con status: "canceled". Restituisce 409 conflict se la generazione è già running o finished, oppure se il modello non supporta l’annullamento delle attività in coda.

Richiesta

curl -X POST https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z/cancel \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Risposta · 200 OK

{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "object": "generation",
  "model": "bytedance/seedance-2.0-fast",
  "endpoint": "bytedance/seedance-2.0-fast/text-to-video",
  "mode": "text-to-video",
  "status": "canceled",
  "input": {
    "prompt": "Lento avvicinamento a un ceramista che modella un vaso all’ora dorata, polvere sospesa nella luce, profondità di campo ridotta",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": true
  },
  "output": null,
  "error": null,
  "cost": {
    "amount_usd": 0,
    "currency": "usd",
    "estimated": false
  },
  "source": "api",
  "created_at": "2026-10-15T09:21:04.512Z",
  "started_at": null,
  "completed_at": "2026-10-15T09:21:06.200Z",
  "retention": "1d",
  "expires_at": "2026-10-16T09:21:06.200Z",
  "purged_at": null
}

Elimina una generazione#

DELETE/api/v1/generations/{id}Chiave API richiesta

Elimina una generazione: rimuove immediatamente i file di output, gli input caricati che nessun’altra generazione usa, il prompt e i dati di input; la generazione non compare più negli elenchi e GET restituisce 404. I dati di fatturazione, inclusi l’addebito nel registro e i totali di utilizzo, vengono conservati. Una generazione ancora queued viene prima annullata e l'importo bloccato rimborsato per intero; se non può più essere annullata (è in esecuzione, o il suo modello non consente di annullare i job in coda), restituisce 409 conflict: attendi che finisca.

Richiesta

curl -X DELETE https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Risposta · 200 OK

{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "object": "generation",
  "deleted": true
}

Oggetto della generazione#

idstring: ID univoco, con prefisso gen_.
objectstring: Sempre "generation".
modelstring: ID modello, per esempio bytedance/seedance-2.0-fast.
endpointstring: ID endpoint a cui è stata inviata l’attività, per esempio bytedance/seedance-2.0-fast/text-to-video.
modestring: Attività: text-to-video, image-to-video, reference-to-video, text-to-image o image-edit.
statusstring: queued → running → succeeded | failed, oppure canceled. Vedi Generazioni.
inputobject: The validated input, with defaults filled in.
outputobject | null: Impostato in caso di successo. Video: { "video": { "url", "content_type" } }. Immagine: { "images": [{ "url", "content_type" }] }. Anche un'immagine sostituita dal controllo di sicurezza (che quindi risulta vuota) ha "safety_filtered": true; viene addebitata come qualsiasi altro risultato.
errorobject | null: Impostato in caso di errore: { "code", "message", "reason", "hint", "retryable", "refunded" }, più param (il campo da modificare) e detail (la dicitura usata dal fornitore), se nota. reason spiega il motivo, per esempio content_blocked, invalid_input, upstream_unavailable. Vedi motivi dell'errore.
costobject: amount_usd, currency ("usd") e estimated: true mentre l’importo è trattenuto, false quando l’addebito è definitivo. Le generazioni non riuscite o annullate costano 0.
pricingobject: custom_price (il tuo prezzo, cioè il prezzo contrattuale o il tuo piano Pro o Max), volume_level (1 = Pro, 2 = Max quando il prezzo è fissato dal piano; altrimenti null), standard_usd (il costo normale di questa richiesta) e fallback: null, oppure { "active", "reason", "message", "standard_usd", "amount_usd" } se è stata eseguita al prezzo di emergenza, comunque non oltre il prezzo ufficiale; impostato da allow_fallback_price e limitato da max_cost_usd.
sourcestring: "api" o "playground" (Studio e pagine dei modelli).
created_atstring: ISO 8601 timestamp of submission.
started_atstring | null: When the model started generating.
completed_atstring | null: When the generation reached a final state.
retentionstring | null: Generazioni API: immediate, 1h, 1d, 7d o 30d. null per le generazioni in Studio, conservate finché non le elimini.
expires_atstring | null: Quando vengono eliminati i contenuti (prompt, input, output e file multimediali). Impostato al termine della generazione. Con immediate, il termine viene anticipato a 10 minuti dopo la prima consegna del risultato.
purged_atstring | null: Impostato una volta eliminati i contenuti. A quel punto output diventa null, input conserva solo i parametri che determinano il prezzo e content_expired spiega il motivo. Costi e date restano.
urlsobject: Solo nella risposta all’invio: URL get e cancel per questa generazione.

Elenca i modelli#

GET/api/v1/modelsPubblico · senza autenticazione

Restituisce tutti i modelli disponibili con i rispettivi endpoint e prezzi aggiornati. I prezzi sono per unit (second di video o image); list_price_usd è il prezzo di listino usato per il confronto e discount_pct il risparmio in percentuale.list_price_source indica di quale prezzo si tratta: official (il prezzo di listino dello sviluppatore) oppure reference (un altro prezzo, indicato da list_price_label — per esempio fal API, per un modello il cui sviluppatore non vende un'API internazionale).

Richiesta

curl https://cheapergen.com/api/v1/models

Risposta · 200 OK

{
  "object": "list",
  "data": [
    {
      "id": "bytedance/seedance-2.0-fast",
      "object": "model",
      "name": "Seedance 2.0 Fast",
      "vendor": "ByteDance",
      "category": "video",
      "available": true,
      "url": "https://cheapergen.com/models/bytedance/seedance-2.0-fast",
      "endpoints": [
        {
          "id": "bytedance/seedance-2.0-fast/text-to-video",
          "mode": "text-to-video",
          "output": "video"
        },
        {
          "id": "bytedance/seedance-2.0-fast/image-to-video",
          "mode": "image-to-video",
          "output": "video"
        },
        {
          "id": "bytedance/seedance-2.0-fast/reference-to-video",
          "mode": "reference-to-video",
          "output": "video"
        }
      ],
      "pricing": {
        "unit": "second",
        "list_price_source": "official",
        "list_price_label": "Official",
        "tiers": [
          {
            "tier": "480p",
            "price_usd": 0.050086,
            "list_price_usd": 0.056246,
            "discount_pct": 11
          },
          {
            "tier": "720p",
            "price_usd": 0.08988,
            "list_price_usd": 0.12096,
            "discount_pct": 26
          }
        ]
      },
      "deprecation": null,
      "upcoming_price_changes": []
    }
  ]
}

Ridotto a un solo modello per brevità.

Recupera un modello#

GET/api/v1/models/{vendor}/{model}Pubblico · senza autenticazione

Restituisce un modello con uno JSON Schema per ogni input del relativo endpoint: utile per creare moduli o convalidare le richieste prima dell’invio. Restituisce 404 not_found per i modelli sconosciuti.

Richiesta

curl https://cheapergen.com/api/v1/models/bytedance/seedream-5.0-pro

Risposta · 200 OK

{
  "id": "bytedance/seedream-5.0-pro",
  "object": "model",
  "name": "Seedream 5.0 Pro",
  "vendor": "ByteDance",
  "category": "image",
  "available": true,
  "description": "ByteDance Seedream 5.0 Pro crea e modifica immagini fotorealistiche fino a 2K, fedeli all’identità del tuo marchio, con modifiche precise a più immagini e testo accurato.",
  "url": "https://cheapergen.com/models/bytedance/seedream-5.0-pro",
  "endpoints": [
    {
      "id": "bytedance/seedream-5.0-pro/text-to-image",
      "mode": "text-to-image",
      "label": "Da testo a immagine",
      "output": "image",
      "input_schema": {
        "type": "object",
        "required": [
          "prompt"
        ],
        "properties": {
          "prompt": {
            "title": "Prompt",
            "description": "Descrivi l’inquadratura: soggetto, azione, movimento della camera, illuminazione e stile.",
            "type": "string",
            "maxLength": 5000
          },
          "aspect_ratio": {
            "title": "Proporzioni",
            "description": "Formato dell'immagine di output.",
            "type": "string",
            "enum": [
              "1:1",
              "4:3",
              "3:4",
              "16:9",
              "9:16",
              "3:2",
              "2:3",
              "21:9"
            ],
            "default": "1:1"
          },
          "size": {
            "title": "Dimensione",
            "description": "1K ≈ 1 megapixel, 2K ≈ 4 megapixel.",
            "type": "string",
            "enum": [
              "1K",
              "2K"
            ],
            "default": "2K"
          },
          "seed": {
            "title": "Seed",
            "description": "Usa lo stesso seed e le stesse impostazioni per riprodurre un risultato. Lascia vuoto per un valore casuale.",
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647
          },
          "webhook_url": {
            "type": "string",
            "format": "uri",
            "title": "Webhook URL",
            "description": "Optional. We POST the finished generation here (signed)."
          }
        },
        "additionalProperties": false
      }
    }
  ],
  "pricing": {
    "unit": "image",
    "notes": [],
    "list_price_source": "official",
    "list_price_label": "Official",
    "tiers": [
      {
        "tier": "1K",
        "detail": "≈1 MP",
        "price_usd": 0.03325,
        "list_price_usd": 0.045,
        "discount_pct": 26
      },
      {
        "tier": "2K",
        "detail": "≈4 MP",
        "price_usd": 0.0665,
        "list_price_usd": 0.09,
        "discount_pct": 26
      }
    ]
  },
  "deprecation": null,
  "upcoming_price_changes": []
}

Ridotto a un solo endpoint per brevità.

Deprecazioni e variazioni di prezzo#

Annunciamo in anticipo aumenti di prezzo e ritiri dei modelli: almeno 14 giorni prima di un aumento (o più, se previsto dal contratto) e 14–30 giorni prima del ritiro. Avvisiamo via email tutti coloro che hanno usato il modello negli ultimi 90 giorni e pubblichiamo l’avviso su changelog (RSS). L’API fornisce le stesse informazioni, così il tuo codice e i tuoi agenti possono reagire:

deprecationobject | null: Disponibili nelle risposte di Elenca i modelli e Recupera un modello. Quando è programmato il ritiro di un modello, vengono impostati: sunset_at (ISO 8601; da quel momento le richieste restituiscono 410 model_delisted e non viene addebitato nulla), replacement (ID dei modelli consigliati, dal più adatto), reason, announced_at e info_url. In caso contrario, null.
upcoming_price_changesarray: Variazioni programmate dei prezzi per livello non ancora entrate in vigore: tier, effective_at, current_price_usd e il nuovo price_usd per unit. Le richieste inviate prima di effective_at pagano il prezzo attuale; il prezzo di una generazione non cambia mai dopo l’invio. Vuoto se non ci sono variazioni programmate.
warningsarray: Nelle risposte di Invia una generazione e Ottieni un preventivo, solo quando ci sono informazioni utili: model_deprecated (con sunset_at e replacement) oppure price_change_scheduled per la fascia richiesta (con effective_at e il nuovo price_usd). Ognuno include un message leggibile e un info_url.

Richiesta

curl https://cheapergen.com/api/v1/models/bytedance/seedance-2.0-fast

Risposta · 200 OK

{
  "id": "bytedance/seedance-2.0-fast",
  "object": "model",
  "…": "…",
  "deprecation": {
    "sunset_at": "2026-11-20T00:00:00.000Z",
    "replacement": [
      "bytedance/seedance-2.0-fast"
    ],
    "reason": "Lo sviluppatore sta ritirando questo modello.",
    "announced_at": "2026-10-21T09:30:00.000Z",
    "info_url": "https://cheapergen.com/changelog#cm2x7k9"
  },
  "upcoming_price_changes": [
    {
      "tier": "720p",
      "effective_at": "2026-11-04T00:00:00.000Z",
      "unit": "second",
      "current_price_usd": 0.08,
      "price_usd": 0.092,
      "change_pct": 15,
      "info_url": "https://cheapergen.com/changelog#cm2x8a1"
    }
  ]
}

Intestazioni Deprecation e Sunset#

Finché è programmato il ritiro di un modello, le risposte che lo riguardano — POST /run, POST /quote e GET /models/{vendor}/{model} — includono le intestazioni standard, così i client HTTP e i gateway API possono registrarle o generare avvisi:

Intestazioni della risposta

Deprecation: @1792575000
Sunset: Fri, 20 Nov 2026 00:00:00 GMT
Link: <https://cheapergen.com/changelog#cm2x7k9>; rel="deprecation"; type="text/html", <https://cheapergen.com/changelog#cm2x7k9>; rel="sunset"; type="text/html"

Deprecation (RFC 9745) indica quando è stato annunciato il ritiro, sotto forma di timestamp Unix; Sunset (RFC 8594) indica quando le richieste non saranno più servite. Per passare a un altro modello basta modificare una riga: invia la stessa richiesta all’endpoint del modello sostitutivo (controlla il suo schema di input per individuare eventuali opzioni diverse).

Con MCP, list_models e get_model includono gli stessi campi deprecation e upcoming_price_changes, oltre a un notice di una sola riga, così gli agenti possono avvisare l’utente prima di affidarsi a un modello che sta per essere ritirato.

Ottieni un preventivo#

POST/api/v1/quote/{endpoint}Pubblico · senza autenticazione

Calcola il prezzo di un input senza eseguirlo. Vengono letti solo i campi che incidono sul prezzo (risoluzione, durata, dimensioni, numero di immagini…); i campi di contenuto come prompt e gli URL di riferimento vengono ignorati, mentre i campi omessi usano i valori predefiniti. available è false se il modello non accetta temporaneamente generazioni.

I video di riferimento aggiungono secondi fatturabili. Per includerli, passa reference_video_durations (secondi, un numero per clip) come stima; /run misura i file reali e riserva il prezzo corrispondente. Consulta Fatturazione.

Richiesta

curl -X POST https://cheapergen.com/api/v1/quote/bytedance/seedance-2.0-fast/text-to-video \
  -H "Content-Type: application/json" \
  -d '{"aspect_ratio":"16:9","resolution":"720p","duration":5}'

Risposta · 200 OK

{
  "amount_usd": 0.4494,
  "list_usd": 0.6048,
  "list_price_source": "official",
  "list_price_label": "Official",
  "discount_pct": 26,
  "available": true,
  "currency": "usd"
}

Invia la tua chiave API per ottenere i tuoi prezzi. Se il tuo account ne ha uno, cioè un prezzo contrattuale o un piano Pro o Max, il preventivo include anche custom_price: true e standard_amount_usd (il prezzo normale), oltre a volume_level (1 o 2) se è stato impostato dal piano Pro (1) o Max (2).

Recupera il tuo account#

GET/api/v1/accountChiave API richiesta

Restituisce il tuo saldo e le impostazioni di ricarica automatica. balance_usd è disponibile per la spesa; image_credit_usd è un credito riservato alle immagini (ad esempio, un credito di benvenuto), che viene usato per i modelli di immagini prima del saldo e mai per i video; reserved_usd è trattenuto dal saldo per le generazioni in corso. Vedi Fatturazione e crediti.

Richiesta

curl https://cheapergen.com/api/v1/account \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Risposta · 200 OK

{
  "object": "account",
  "email": "you@company.com",
  "balance_usd": 42.5,
  "image_credit_usd": 0,
  "reserved_usd": 1.2,
  "auto_topup": {
    "enabled": true,
    "threshold_usd": 10,
    "amount_usd": 50
  },
  "limits": {
    "unlimited": false,
    "concurrent_generations": 20,
    "in_flight": 3,
    "requests_per_second": 10,
    "burst": 20,
    "tier": null
  }
}

limits indica i limiti API del tuo account e quante sue generazioni sono in corso; se l'account non ha limiti, valgono null, con unlimited: true. Vedi Limiti di frequenza.

Visualizza i tuoi prezzi#

GET/api/v1/account/pricingChiave API richiesta

Restituisce il tuo piano mensile, il livello di volume che sblocca e i tuoi prezzi per ogni livello accanto a quelli standard. Aggiungi ?model={vendor}/{model} per un singolo modello. Il pagamento a consumo non richiede un piano: in quel caso plan è null e custom è false. Vedi Piani mensili.

customboolean: true quando un piano Pro o Max o un prezzo contrattuale riduce uno dei tuoi prezzi.
planobject | null: Il tuo piano mensile: { "id", "status" }, ad esempio pro e active (starter, pro o max). null senza piano.
volumeobject: level: 1 mentre Pro è attivo, 2 mentre è attivo Max, altrimenti null.
rulesarray: I tuoi prezzi contrattuali, attivi e programmati: scope, status, discount_pct o unit_price_usd, starts_at, ends_at, e un description leggibile.
modelsarray: Ogni modello incluso nel tuo piano o in una regola: id, name, unit e tiers, ciascuno con price_usd (il tuo prezzo), standard_price_usd, custom, volume_level (quando è fissato dal piano) e available.

Richiesta

curl "https://cheapergen.com/api/v1/account/pricing?model=bytedance/seedance-2.0-fast" \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Risposta · 200 OK

{
  "object": "customer_pricing",
  "custom": true,
  "plan": {
    "id": "pro",
    "status": "active"
  },
  "volume": {
    "level": 1
  },
  "rules": [],
  "models": [
    {
      "id": "bytedance/seedance-2.0-fast",
      "name": "Seedance 2.0 Fast",
      "unit": "second",
      "tiers": [
        "…"
      ]
    }
  ]
}

Carica un file#

POST/api/v1/uploadsChiave API richiesta

Carica un file da usare come URL di input: primo fotogramma, immagine di riferimento, video di riferimento o clip audio di riferimento. In alternativa, puoi passare direttamente qualsiasi URL HTTPS pubblico.

Tipo	Formati	Dimensione massima
Immagine	PNG, JPEG, WebP, GIF	20 MB
Video	MP4, MOV	50 MB
Audio	MP3, WAV, M4A (i modelli al momento accettano MP3 o WAV)	15 MB

Caricamento diretto (consigliato)#

Invia JSON con filename, content_type e size del file, espressi in byte. Riceverai un upload_url valido per poco tempo; usa PUT per caricare i byte originali a quell’indirizzo con gli esatti headers restituiti, poi usa url come input. Il file viene inviato direttamente allo storage, quindi non ci sono limiti aggiuntivi sulla dimensione della richiesta oltre a quelli indicati sopra. L’URL di upload scade dopo 15 minuti. size deve essere la dimensione esatta del file in byte: invia con PUT esattamente quel numero di byte con Content-Length (niente corpo chunked o in streaming). Lo storage risponde 403 a qualsiasi altra cosa.

Richiesta

curl -X POST https://cheapergen.com/api/v1/uploads \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"choreo.mp4","content_type":"video/mp4","size":8421903}'

Risposta · 201 Created

{
  "object": "upload",
  "method": "PUT",
  "upload_url": "https://storage.example.com/media/uploads/7f3k2m9q/0b8d2c5e1a7f4h6j9k3m.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&…",
  "headers": {
    "Content-Type": "video/mp4"
  },
  "url": "https://cdn.cheapergen.com/uploads/7f3k2m9q/0b8d2c5e1a7f4h6j9k3m.mp4",
  "kind": "video",
  "content_type": "video/mp4",
  "bytes": 8421903,
  "expires_at": "2026-10-15T09:36:04.000Z"
}

Poi carica i byte

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @choreo.mp4

Caricamento multipart#

In alternativa, usa il formato multipart/form-data con un campo file: conserveremo noi il file (201 Created con url). I byte passano dalla nostra API, dove il corpo della richiesta è limitato a circa 4,5 MB: per i file più grandi usa il caricamento diretto. Se il caricamento diretto non è disponibile in una distribuzione, la richiesta JSON restituisce 501 direct_upload_unavailable; in tal caso usa multipart.

Richiesta

curl -X POST https://cheapergen.com/api/v1/uploads \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -F "file=@first-frame.png"

Risposta · 201 Created

{
  "object": "upload",
  "url": "https://cdn.cheapergen.com/uploads/7f3k2m9q/0b8d2c5e1a7f4h6j9k3m.png",
  "kind": "image",
  "content_type": "image/png",
  "bytes": 1834221
}

Usare un'immagine caricata#

Passa l'URL ricevuto nel campo image di un endpoint da immagine a video o di modifica:

curl -X POST https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/image-to-video \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "La camera si avvicina mentre lei si volta e sorride; i capelli si muovono al vento",
  "image_url": "https://cdn.cheapergen.com/uploads/7f3k2m9q/0b8d2c5e1a7f4h6j9k3m.png",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}'

Riferimenti per modello

Ogni modello ha una propria pagina API, con tipo, valore predefinito e valori consentiti per ogni campo, oltre a esempi da copiare e incollare. Inizia dall’elenco dei modelli.

Qualcosa non è chiaro o manca? Scrivi a support@cheapergen.com: leggiamo ogni messaggio.