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}:billingdi 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.
- Arrotondare verso l'alto la durata misurata di ciascun video d'input indipendentemente, poi sommare:
input_seconds = sum(ceil(each_video_duration)). - Arrotondare la durata dell'output al secondo intero più vicino, con secondi frazionari positivi arrotondati verso l'alto.
- Aggiungere i secondi fatturabili di input e output.
- Moltiplicare per
effective_unit_rate, dividere peraccount_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.
