APIMaster.ai

Preventivi Seedance e ricevute di fatturazione

Stima i costi di generazione Seedance e verifica l'addebito finale utilizzando ricevute di fatturazione autenticate e persistenti.

Preventivi Seedance e ricevute di fatturazione

Si applica a seedance-2.0, seedance-2.5, seedance-2.0-fast e seedance-2.0-mini, su tutti i canali di generazione. URL base: https://apimaster.ai/v1 (https://apimaster.ai/v1). Autenticare tutte le richieste con Authorization: Bearer YOUR_API_KEY.

Ottenere un preventivo

POST https://apimaster.ai/v1/videos/quote accetta gli stessi parametri JSON di una richiesta standard di generazione video, inclusi model, prompt, duration, resolution, video_urls e altre impostazioni di generazione supportate. I preventivi per la generazione bozza, l'aggiornamento della bozza e il remix non sono attualmente supportati.

curl "https://apimaster.ai/v1/videos/quote" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.0","prompt":"A paper boat on a pond","duration":4,"resolution":"480p","generate_audio":false}'

La risposta contiene object: "video.quote", quote_id, expires_at (secondi Unix), binding: false, funds_reserved: false e un oggetto billing descritto di seguito. Il preventivo ha un periodo di validità consultivo di cinque minuti. Non addebita fondi, non crea un'attività e non avvia l'elaborazione del provider. billing.reserved_amount è quindi "0.000000". L'ID del preventivo è informativo; non è un token di autorizzazione o di blocco del prezzo e non deve essere inviato con la generazione.

Il prezzo viene ricalcolato al momento dell'invio effettivo e congelato per quell'attività. Un preventivo non è una garanzia di addebito massimo. L'attività completata può costare di più o di meno rispetto al preventivo. Le richieste con durata automatica utilizzano una stima di output di 30 secondi; requested_output_seconds è -1.

La generazione rimane soggetta alla convalida del provider. Per le richieste di estensione video Seedance 2.5, impostare esplicitamente aspect_ratio: "adaptive"; un rifiuto del provider viene gestito tramite l'ordinario ciclo di vita del rimborso.

Recuperare l'estratto dell'attività

curl "https://apimaster.ai/v1/videos/task_xxx/billing" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/videos/{task_id}/billing restituisce object: "video.billing_receipt", billing e customer_billing. Usa una chiave API dell'account proprietario. Con la chiave originale, GET /v1/video-submissions/by-key espone la fatturazione del cliente in data.customer_billing. Con final: true, net_amount indica l'addebito netto definitivo come stringa decimale in USD. Una vecchia attività con un rimborso confermato può restituire un netto definitivo di zero anche se i costi del fornitore non sono stati verificati. La consultazione per ID restituisce HTTP 404 per attività di altri account o se mancano sia la ricevuta sia la prova del rimborso. Consulta i campi di ritentativo per sapere se puoi inviare di nuovo.

Lo stesso oggetto billing è incluso in entrambe le risposte di interrogazione attività:

  • GET /v1/videos/{task_id}: billing di livello superiore.
  • GET /v1/video/generations/{task_id}: data.billing.

settlement_status è pending, settled o refunded; le risposte di preventivo utilizzano estimate. Il completamento dell'attività e il regolamento finanziario sono separati: considerare gli importi come definitivi solo quando l'estratto è settled o refunded. Le richieste ripetute di estratto non eseguono generazione, regolamento o rimborsi. Gli estratti finalizzati mantengono lo stesso ID estratto e i contenuti, incluso dopo un rimborso.

Esempi completi di richiesta e risposta

Entrambi gli esempi utilizzano Seedance 2.0 a 480P, un output richiesto di 4 secondi, un riferimento misurato a 4,042 secondi, moltiplicatore canale 1 e moltiplicatore account 1,05. Le durate di completamento e gli importi provengono da un test dal vivo; l'offerta è un esempio illustrativo assemblato per input corrispondenti. Gli ID e gli URL dei media sono segnaposto. Le tariffe effettive provengono dalla risposta API.

1. Ottenere un preventivo

POST https://apimaster.ai/v1/videos/quote, JSON della richiesta:

{
  "model": "seedance-2.0",
  "prompt": "A paper boat moves gently on a pond.",
  "duration": 4,
  "resolution": "480p",
  "video_urls": [
    "https://example.com/reference.mp4"
  ]
}
Campo Tipo Significato
model string ID del modello, seedance-2.0 in questo caso.
prompt string Prompt di generazione.
duration integer Secondi di output richiesti, non la durata del video di riferimento.
resolution string Risoluzione di output, 480p in questo caso.
video_urls array URL dei video di riferimento. Sostituire il segnaposto con media accessibili; l'host misura ciascun file.

Risposta del preventivo:

{
  "object": "video.quote",
  "quote_id": "quote_example",
  "expires_at": 1790949324,
  "binding": false,
  "funds_reserved": false,
  "billing": {
    "schema_version": "1",
    "settlement_status": "estimate",
    "model": "seedance-2.0",
    "resolution": "480P",
    "tariff_variant": "480P-input",
    "tariff_revision": "sd-v1-b79a35d3a29af9af",
    "currency": "USD",
    "unit": "second",
    "base_unit_rate": "0.04319",
    "channel_multiplier": 1,
    "account_multiplier": 1.05,
    "effective_unit_rate": "0.0453495",
    "requested_output_seconds": 4,
    "estimated_output_seconds": 4,
    "estimated_billable_seconds": 9,
    "input_videos": [
      {
        "index": 0,
        "media_id": "media_example_hash",
        "measured_seconds": 4.042,
        "billable_seconds": 5,
        "duration_source": "apimaster_probe"
      }
    ],
    "billable_input_video_seconds": 5,
    "output": null,
    "billable_seconds": null,
    "rounding": {
      "amount_formula": "round(total_billable_seconds * effective_unit_rate / account_unit_usd) * account_unit_usd",
      "effective_unit_rate": "nearest_decimal_12_places_half_up",
      "input_video": "ceil_each_file_then_sum",
      "money": "nearest_account_unit_half_up",
      "output_video": "nearest_integer_half_up"
    },
    "estimated_amount": "0.408146",
    "reserved_amount": "0.000000",
    "additional_debit_amount": "0.000000",
    "final_debit_amount": null,
    "refunded_amount": "0.000000",
    "net_amount": null,
    "initial_quota_units": 0,
    "final_quota_units": null,
    "account_unit_usd": "0.000002",
    "media_charges": {
      "audio": "0.000000",
      "image": "0.000000",
      "input_video_unrounded": "0.2267475",
      "other_reference": "0.000000",
      "output_video_unrounded": "0.181398"
    },
    "final_debit_may_exceed_estimate": true,
    "created_at": 1790949024,
    "settled_at": null
  }
}

L'input di 4,042 secondi viene arrotondato a 5 secondi. Con 4 secondi di output stimati, il preventivo copre 9 secondi e costa 0,408146 USD. Il preventivo non addebita fondi; gli importi finali rimangono null.

2. Inviare la generazione e interrogare il completamento

Dopo l'invio a POST https://apimaster.ai/v1/videos/generations, l'output iniziale contiene l'ID dell'attività:

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_example"
    }
  ]
}

Quindi interrogare GET https://apimaster.ai/v1/videos/task_example utilizzando una chiave API dallo stesso account. Dopo il completamento della generazione e del regolamento:

{
  "actual_time": 189,
  "billing": {
    "schema_version": "1",
    "receipt_id": "bill_task_example",
    "task_id": "task_example",
    "settlement_status": "settled",
    "model": "seedance-2.0",
    "resolution": "480P",
    "tariff_variant": "480P-input",
    "tariff_revision": "sd-v1-b79a35d3a29af9af",
    "currency": "USD",
    "unit": "second",
    "base_unit_rate": "0.04319",
    "channel_multiplier": 1,
    "account_multiplier": 1.05,
    "effective_unit_rate": "0.0453495",
    "requested_output_seconds": 4,
    "estimated_output_seconds": 4,
    "estimated_billable_seconds": 9,
    "input_videos": [
      {
        "index": 0,
        "media_id": "media_example_hash",
        "measured_seconds": 4.042,
        "billable_seconds": 5,
        "duration_source": "apimaster_probe"
      }
    ],
    "billable_input_video_seconds": 5,
    "output": {
      "actual_seconds": 4,
      "billable_seconds": 4,
      "duration_source": "provider_reported"
    },
    "billable_seconds": 9,
    "rounding": {
      "amount_formula": "round(total_billable_seconds * effective_unit_rate / account_unit_usd) * account_unit_usd",
      "effective_unit_rate": "nearest_decimal_12_places_half_up",
      "input_video": "ceil_each_file_then_sum",
      "money": "nearest_account_unit_half_up",
      "output_video": "nearest_integer_half_up"
    },
    "estimated_amount": "0.408146",
    "reserved_amount": "0.408146",
    "additional_debit_amount": "0.000000",
    "final_debit_amount": "0.408146",
    "refunded_amount": "0.000000",
    "net_amount": "0.408146",
    "initial_quota_units": 204073,
    "final_quota_units": 204073,
    "account_unit_usd": "0.000002",
    "media_charges": {
      "audio": "0.000000",
      "image": "0.000000",
      "input_video_unrounded": "0.2267475",
      "other_reference": "0.000000",
      "output_video_unrounded": "0.181398"
    },
    "final_debit_may_exceed_estimate": true,
    "created_at": 1790949024,
    "settled_at": 1790949213
  },
  "completed_at": 1790949213,
  "created_at": 1790949024,
  "id": "task_example",
  "metadata": {
    "url": "https://apimaster.ai/v1/videos/task_example/content"
  },
  "model": "seedance-2.0",
  "object": "video",
  "progress": 100,
  "status": "completed",
  "task_id": "task_example",
  "usage": {
    "completion_tokens": 80770
  }
}

L'addebito iniziale è uguale al costo finale in questo caso, senza addebiti aggiuntivi o rimborsi. billing.output.actual_seconds è l'output effettivo; actual_time è il tempo di elaborazione. usage.completion_tokens non determina l'addebito. I campi facoltativi possono variare in base al canale.

GET https://apimaster.ai/v1/videos/task_example/billing restituisce { "object": "video.billing_receipt", "billing": ... } con lo stesso oggetto billing. L'interrogazione di compatibilità GET https://apimaster.ai/v1/video/generations/task_example lo colloca sotto data.billing.

Campi della risposta esterna

Campo Tipo Significato
object string Tipo di risposta: video.quote, video o video.billing_receipt.
quote_id string Identificatore informativo del preventivo; non è un blocco del prezzo o un'autorizzazione alla generazione.
expires_at integer Scadenza consultiva del preventivo in secondi Unix, normalmente creazione più 300 secondi.
binding boolean Attualmente false; il preventivo non garantisce un importo finale.
funds_reserved boolean Attualmente false; il preventivo non addebita né riserva fondi.
billing object Dettagli di fatturazione documentati individualmente di seguito.
code integer Codice di risposta dell'invio; 200 significa inviato, non completato.
data array Elenco delle attività inviate; l'interrogazione di compatibilità utilizza invece un oggetto per data.
data[].status string Stato dell'invio, inviato in questo esempio.
data[].task_id string Identificatore pubblico dell'attività utilizzato per le interrogazioni successive.
id string ID pubblico dell'attività nell'interrogazione di completamento.
task_id string Identificatore dell'attività, uguale a id in questo esempio.
model string Nome pubblico del modello di generazione.
status string Stato dell'attività; completed significa che la generazione è terminata. Verificare billing.settlement_status per il regolamento finale.
progress number Percentuale di avanzamento; 100 al completamento in questo esempio.
actual_time number Secondi di elaborazione dell'attività, non la durata del video di output.
created_at integer Timestamp di creazione dell'attività in secondi Unix.
completed_at integer Timestamp di completamento dell'attività in secondi Unix.
metadata object Metadati del risultato di generazione.
metadata.url string URL di download del contenuto video.
usage object Informazioni sull'utilizzo del provider; può essere assente a seconda del canale.
usage.completion_tokens integer Numero di token del provider; non utilizzato per la fatturazione al secondo di questi quattro modelli.

Schema di fatturazione

Tutti gli importi monetari e le tariffe unitarie sono stringhe decimali. Le durate temporali sono in secondi. I campi nullabili sono JSON null fino a quando non sono disponibili.

Campo Tipo Significato
schema_version string Versione dello schema di fatturazione, "1" in questo esempio.
receipt_id string Identificatore stabile dell'estratto; assente dai preventivi.
task_id string ID pubblico dell'attività collegato all'estratto; assente dai preventivi.
settlement_status string estimate, pending, settled, refunded
model string ID pubblico del modello applicato.
resolution string Risoluzione normalizzata utilizzata per la fatturazione.
tariff_variant string Fascia tariffaria; -input indica riferimenti video, con questa tariffa applicata a input e output.
tariff_revision string Impronta digitale del modello, fascia tariffaria, tariffa base configurata e versione delle regole di fatturazione
currency string Valuta di addebito, attualmente USD.
unit string Unità della tariffa; second significa per secondo.
base_unit_rate decimal string Prezzo base configurato per secondo per questo modello e fascia.
channel_multiplier number Moltiplicatore di prezzo aggregato del canale applicato.
account_multiplier number Moltiplicatore account/gruppo applicato, 1,05 in questo esempio.
effective_unit_rate decimal string Tariffa per secondo applicata, congelata all'invio e arrotondata a 12 cifre decimali.
requested_output_seconds integer Durata di output richiesta; -1 per durata automatica
estimated_output_seconds integer Secondi di output stimati; la durata automatica è stimata a 30 secondi.
estimated_billable_seconds integer Secondi totali stimati fatturabili iniziali, inclusi video di riferimento e output stimato.
input_videos array Misurazioni del server per riferimento, nell'ordine della richiesta
input_videos[].index integer Posizione del video di riferimento nella richiesta, a partire da zero.
input_videos[].media_id string Hash dei media specifico dell'account o ID dell'asset posseduto; nessun URL del video di riferimento viene restituito.
input_videos[].measured_seconds number or null Durata misurata dal server prima dell'arrotondamento; può essere null per asset cached più vecchi
input_videos[].billable_seconds integer Durata fatturabile arrotondata di questo riferimento
input_videos[].duration_source string apimaster_probe o apimaster_asset_cache
billable_input_video_seconds integer Somma dei secondi fatturabili per riferimento
output object or null Informazioni sulla durata finale dell'output, disponibili dopo il regolamento riuscito
output.actual_seconds number or null Durata di output effettiva riportata/misurata; null se non disponibile
output.billable_seconds integer Secondi di output effettivamente utilizzati nel regolamento
output.duration_source string provider_reported, apimaster_probe, provider_billable_seconds, requested_duration_fallback o reservation_fallback
billable_seconds integer or null Secondi fatturabili finali combinati input/output
rounding object Regole di arrotondamento per input, output e denaro e formula dell'importo
estimated_amount decimal string Costo stimato iniziale, non un importo finale o una garanzia di addebito massimo.
reserved_amount decimal string Addebito iniziale dell'account all'invio, zero per i preventivi; non è un blocco di autorizzazione bancaria.
additional_debit_amount decimal string Addebito aggiuntivo quando l'importo finale supera l'addebito iniziale.
final_debit_amount decimal string or null Costo netto finale dell'attività dopo gli aggiustamenti; zero dopo un rimborso completo
net_amount decimal string or null Costo netto finale dell'attività dopo gli aggiustamenti; zero dopo un rimborso completo
refunded_amount decimal string Importo restituito dall'addebito iniziale; uguale all'addebito iniziale in caso di rimborso completo.
initial_quota_units integer Unità esatte dell'account addebitate inizialmente; zero per i preventivi.
final_quota_units integer or null Unità esatte dell'account del costo netto finale; null mentre è in attesa, zero dopo un rimborso completo.
account_unit_usd decimal string "0.000002" per unità dell'account
media_charges object image, audio, other_reference sono zero con la tariffa attuale; input_video_unrounded e output_video_unrounded separano i componenti video prima dell'arrotondamento monetario finale
final_debit_may_exceed_estimate boolean true; il preventivo non è un limite di spesa rigido
created_at integer Timestamp di creazione dei dettagli di fatturazione in secondi Unix.
settled_at integer or null Timestamp del regolamento finale o del rimborso in secondi Unix; null fino alla finalizzazione.
Campo Tipo Significato
rounding.input_video string ceil_each_file_then_sum: arrotondare ogni file di input verso l'alto, poi sommare.
rounding.output_video string nearest_integer_half_up: secondo di output più vicino, secondi frazionari arrotondati verso l'alto.
rounding.effective_unit_rate string nearest_decimal_12_places_half_up: arrotondare la tariffa effettiva a 12 cifre decimali.
rounding.money string nearest_account_unit_half_up: arrotondare l'importo combinato alle unità dell'account.
rounding.amount_formula string Formula dell'importo combinato finale; gli importi di input e output non vengono arrotondati separatamente.
media_charges.input_video_unrounded decimal string Componente video di input prima dell'arrotondamento monetario.
media_charges.output_video_unrounded decimal string Componente video di output prima dell'arrotondamento monetario.
media_charges.image decimal string Supplemento immagine separato, attualmente zero.
media_charges.audio decimal string Supplemento audio separato, attualmente zero.
media_charges.other_reference decimal string Supplemento per altri riferimenti, attualmente zero.

Ricalcolare l'importo finale

Con video di riferimento, la fascia video-input si applica sia ai secondi di output che ai secondi dei video di riferimento. Immagini e audio non hanno supplementi separati con la tariffa Seedance attuale. I conteggi dei token e il costo del provider non sono input di fatturazione.

  1. Arrotondare verso l'alto la durata misurata di ciascun video d'input indipendentemente, poi sommare: input_seconds = sum(ceil(each_video_duration)).
  2. Arrotondare la durata dell'output al secondo intero più vicino, con secondi frazionari positivi arrotondati verso l'alto.
  3. Aggiungere i secondi fatturabili di input e output.
  4. Moltiplicare per effective_unit_rate, dividere per account_unit_usd, poi arrotondare il totale una volta all'unità dell'account intera più vicina, con unità frazionarie positive arrotondate verso l'alto.
final_quota_units = round_half_up(billable_seconds × effective_unit_rate / 0.000002)
net_amount = final_quota_units × 0.000002
net_amount = reserved_amount + additional_debit_amount - refunded_amount

Utilizzare l'aritmetica decimale. Non arrotondare separatamente i componenti monetari di input e output. Ad esempio, un'attività Seedance 2.0 di 4 secondi a 480P, senza video di riferimento, con tariffa base 0.07031, moltiplicatore canale 1 e moltiplicatore account 1.05, ha una tariffa effettiva di 0.0738255 e un costo netto di 0.295302 USD (147651 unità dell'account).

APIMaster misura la durata dei video di riferimento, anziché fidarsi dei campi client come input_seconds o reference_seconds. La duration/seconds richiesta controlla la durata dell'output. Per gli output, il regolamento preferisce la durata riportata dal provider e misura l'output quando necessario; le misurazioni non disponibili possono fare riferimento ai secondi fatturabili del provider o alla durata richiesta/riservata. L'estratto etichetta esplicitamente la fonte. Un fallback non viene mai etichettato come durata effettiva misurata in modo indipendente. Gli asset cached esistenti o le bozze più vecchie ereditate possono non avere dettagli di misurazione completi per file.

actual_time nella risposta video è il tempo di elaborazione dell'attività, non l'output video. usage.completion_tokens, quando presente, è informativo.

Fallimenti e rimborsi

I fallimenti delle attività del provider e il timeout configurato di 24 ore per le attività non completate attivano un rimborso automatico completo. I loro estratti rimangono recuperabili e mostrano refunded con importo netto zero una volta riuscito l'accredito. Gli errori temporanei di polling/rete non rimborsano immediatamente né annullano un'attività; l'elaborazione viene riprovata.

Un fallimento dell'invio confermato come non addebitato viene rimborsato. Un esito ambiguo dell'invio viene trattenuto per la riconciliazione automatica (prima riconciliazione asincrona dopo circa 20 minuti; gli esiti ancora sconosciuti dopo 24 ore vengono rimborsati durante la riconciliazione). Se l'invio non ha creato un'attività pubblica, non esiste un estratto collegato all'attività per quel tentativo. Un preventivo non è una riserva e non richiede rilascio.

Non esiste un endpoint pubblico di annullamento Seedance. Disconnettersi o interrompere il polling non annulla un'attività. I controlli dello stato dell'attività impediscono che il polling ripetuto applichi nuovamente lo stesso regolamento/rimborso di completamento, mentre l'endpoint dell'estratto è solo di lettura. Queste non sono una garanzia universale di esecuzione esatta una volta per ogni fallimento dell'infrastruttura; le operazioni finanziarie in attesa non devono essere considerate finalizzate.

Idempotenza Seedance e recupero degli invii