APIMaster.ai

Devis Seedance et reçus de facturation

Estimer les coûts de génération Seedance et vérifier le débit final à l'aide de reçus de facturation authentifiés et persistants.

Devis Seedance et reçus de facturation

S'applique à seedance-2.0, seedance-2.5, seedance-2.0-fast et seedance-2.0-mini, sur tous les canaux de génération. URL de base : https://apimaster.ai/v1 (https://apimaster.ai/v1). Authentifiez toutes les requêtes avec Authorization: Bearer YOUR_API_KEY.

Obtenir une estimation

POST https://apimaster.ai/v1/videos/quote accepte les mêmes paramètres JSON qu'une requête de génération vidéo standard, notamment model, prompt, duration, resolution, video_urls et d'autres paramètres de génération pris en charge. La génération de brouillons, les mises à niveau de brouillons et les devis de remix ne sont pas pris en charge actuellement.

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 réponse contient object: "video.quote", quote_id, expires_at (secondes Unix), binding: false, funds_reserved: false et un objet billing décrit ci-dessous. Le devis a une période de validité indicative de cinq minutes. Il ne débite pas de fonds, ne crée pas de tâche et ne déclenche pas la génération du fournisseur. billing.reserved_amount vaut donc "0.000000". L'ID de devis est informatif ; ce n'est pas un jeton d'autorisation ou de verrouillage de prix et il n'a pas besoin d'être soumis avec la génération.

La tarification est recalculée à la soumission réelle et gelée pour cette tâche. Une estimation n'est pas une garantie de facturation maximale. La tâche terminée peut coûter plus ou moins que l'estimation. Les requêtes à durée automatique utilisent une estimation de sortie de 30 secondes ; requested_output_seconds vaut -1.

La génération reste soumise à la validation du fournisseur. Pour les requêtes d'extension vidéo Seedance 2.5, définissez explicitement aspect_ratio: "adaptive" ; un rejet du fournisseur est traité via le cycle de remboursement normal.

Récupérer le reçu de la tâche

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

GET /v1/videos/{task_id}/billing renvoie object: "video.billing_receipt", billing et customer_billing. Utilisez une clé API du compte propriétaire. Avec la clé d’origine, GET /v1/video-submissions/by-key expose la facturation du client dans data.customer_billing. Si final: true, net_amount indique le débit net définitif sous forme de chaîne décimale en USD. Une ancienne tâche dont le remboursement est confirmé peut afficher un net définitif nul alors que la facturation du fournisseur reste à vérifier. Une tâche hors du compte ou sans reçu ni preuve de remboursement renvoie HTTP 404 lors de la consultation par identifiant. Les champs de nouvelle tentative déterminent si un nouvel envoi est possible.

Le même objet billing est inclus dans les deux réponses d'interrogation de tâche :

  • GET /v1/videos/{task_id} : billing au niveau supérieur.
  • GET /v1/video/generations/{task_id} : data.billing.

settlement_status vaut pending, settled ou refunded ; les réponses de devis utilisent estimate. L'achèvement de la tâche et le règlement financier sont distincts : ne considérez les montants comme définitifs que lorsque le reçu est settled ou refunded. Les demandes répétées de reçu ne déclenchent ni génération, ni règlement, ni remboursement. Les reçus finalisés conservent le même ID de reçu et le même contenu, y compris après un remboursement.

Exemples complets de requête et de réponse

Les deux exemples utilisent Seedance 2.0 en 480P, une sortie demandée de 4 secondes, une référence mesurée à 4,042 seconde, un multiplicateur de canal de 1 et un multiplicateur de compte de 1,05. Les durées et montants d'achèvement proviennent d'un test réel ; le devis est un exemple illustratif assemblé pour des entrées correspondantes. Les ID et les URL de média sont des espaces réservés. Les tarifs réels proviennent de votre réponse API.

1. Obtenir un devis

POST https://apimaster.ai/v1/videos/quote, JSON de requête :

{
  "model": "seedance-2.0",
  "prompt": "A paper boat moves gently on a pond.",
  "duration": 4,
  "resolution": "480p",
  "video_urls": [
    "https://example.com/reference.mp4"
  ]
}
Champ Type Signification
model string ID du modèle, seedance-2.0 ici.
prompt string Invite de génération.
duration integer Secondes de sortie demandées, pas la durée de la vidéo de référence.
resolution string Résolution de sortie, 480p ici.
video_urls array URL des vidéos de référence. Remplacez l'espace réservé par un média accessible ; le serveur mesure chaque fichier.

Réponse du devis :

{
  "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'entrée de 4,042 seconde est arrondie à 5 secondes. Avec 4 secondes de sortie estimées, l'estimation couvre 9 secondes et coûte 0,408146 USD. Le devis ne débite pas de fonds ; les montants finaux restent nuls.

2. Soumettre la génération et interroger l'achèvement

Après soumission à POST https://apimaster.ai/v1/videos/generations, la réponse initiale contient l'ID de tâche :

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

Interrogez ensuite GET https://apimaster.ai/v1/videos/task_example à l'aide d'une clé API du même compte. Une fois la génération et le règlement terminés :

{
  "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
  }
}

Le débit initial est égal au coût final ici, sans débit ni remboursement supplémentaires. billing.output.actual_seconds est la durée de sortie ; actual_time est le temps de traitement. usage.completion_tokens ne détermine pas la facturation. Les champs facultatifs peuvent varier selon le canal.

GET https://apimaster.ai/v1/videos/task_example/billing renvoie { "object": "video.billing_receipt", "billing": ... } avec le même objet billing. La requête de compatibilité GET https://apimaster.ai/v1/video/generations/task_example le place sous data.billing.

Champs de réponse externes

Champ Type Signification
object string Type de réponse : video.quote, video ou video.billing_receipt.
quote_id string Identifiant de devis informatif ; ni un verrouillage de prix ni une autorisation de génération.
expires_at integer Expiration indicative du devis en secondes Unix, normalement la création plus 300 secondes.
binding boolean Actuellement false ; le devis ne garantit pas un montant final.
funds_reserved boolean Actuellement false ; un devis ne débite ni ne réserve de fonds.
billing object Détails de facturation documentés individuellement ci-dessous.
code integer Code de réponse de soumission ; 200 signifie soumis, pas terminé.
data array Liste des tâches soumises ; la requête de compatibilité utilise plutôt un objet pour data.
data[].status string Statut de soumission, submitted dans cet exemple.
data[].task_id string Identifiant de tâche public utilisé pour les requêtes ultérieures.
id string ID de tâche public dans la requête d'achèvement.
task_id string Identifiant de tâche, égal à id dans cet exemple.
model string Nom public du modèle de génération.
status string Statut de la tâche ; completed signifie que la génération est terminée. Vérifiez billing.settlement_status pour le règlement final.
progress number Pourcentage de progression ; 100 à l'achèvement dans cet exemple.
actual_time number Secondes de traitement de la tâche, pas la durée de la vidéo de sortie.
created_at integer Horodatage de création de la tâche en secondes Unix.
completed_at integer Horodatage d'achèvement de la tâche en secondes Unix.
metadata object Métadonnées du résultat de génération.
metadata.url string URL de téléchargement du contenu vidéo.
usage object Informations d'utilisation du fournisseur ; peuvent être absentes selon le canal.
usage.completion_tokens integer Nombre de tokens du fournisseur ; non utilisé pour la facturation à la seconde de ces quatre modèles.

Schéma de facturation

Tous les montants monétaires et taux unitaires sont des chaînes décimales. Les durées sont en secondes. Les champs nullables sont null en JSON jusqu'à être disponibles.

Champ Type Signification
schema_version string Version du schéma de facturation, "1" dans cet exemple.
receipt_id string Identifiant stable du reçu ; absent des devis.
task_id string ID de tâche public lié au reçu ; absent des devis.
settlement_status string estimate, pending, settled, refunded
model string ID de modèle public appliqué.
resolution string Résolution normalisée utilisée pour la facturation.
tariff_variant string Palier tarifaire ; -input indique des références vidéo, ce tarif s'appliquant à l'entrée et à la sortie.
tariff_revision string Empreinte du modèle, du palier tarifaire, du tarif de base configuré et de la version des règles de facturation
currency string Devise de facturation, actuellement USD.
unit string Unité du tarif ; second signifie par seconde.
base_unit_rate decimal string Prix de base configuré par seconde pour ce modèle et ce palier.
channel_multiplier number Multiplicateur de tarification global du canal appliqué.
account_multiplier number Multiplicateur de compte/groupe appliqué, 1,05 dans cet exemple.
effective_unit_rate decimal string Tarif par seconde appliqué, gelé à la soumission et arrondi à 12 décimales.
requested_output_seconds integer Durée de sortie demandée ; -1 pour une durée automatique
estimated_output_seconds integer Secondes de sortie estimées ; une durée automatique est estimée à 30 secondes.
estimated_billable_seconds integer Nombre total estimé initial de secondes facturables, incluant les vidéos de référence et la sortie estimée.
input_videos array Mesures serveur par référence, dans l'ordre de la requête
input_videos[].index integer Position de la vidéo de référence dans la requête, à partir de zéro.
input_videos[].media_id string Hachage de média à portée du compte ou ID d'actif possédé ; aucune URL de vidéo de référence n'est renvoyée.
input_videos[].measured_seconds number ou null Durée mesurée par le serveur avant arrondi ; peut être null pour les anciens actifs en cache
input_videos[].billable_seconds integer Durée facturable arrondie de cette référence
input_videos[].duration_source string apimaster_probe ou apimaster_asset_cache
billable_input_video_seconds integer Somme des secondes facturables par référence
output object ou null Informations sur la durée de sortie finale, disponibles après un règlement réussi
output.actual_seconds number ou null Durée de sortie réelle signalée/détectée ; null si indisponible
output.billable_seconds integer Secondes de sortie réellement utilisées dans le règlement
output.duration_source string provider_reported, apimaster_probe, provider_billable_seconds, requested_duration_fallback ou reservation_fallback
billable_seconds integer ou null Secondes facturables finales combinées entrée/sortie
rounding object Règles d'arrondi des entrées, des sorties et des montants, et formule de calcul du montant
estimated_amount decimal string Coût initial estimé, ni un montant final ni une garantie de facturation maximale.
reserved_amount decimal string Débit initial du compte à la soumission, zéro pour les devis ; pas une autorisation de retenue bancaire.
additional_debit_amount decimal string Débit supplémentaire lorsque le coût final dépasse le débit initial.
final_debit_amount decimal string ou null Coût net final de la tâche après ajustements ; zéro après un remboursement complet
net_amount decimal string ou null Coût net final de la tâche après ajustements ; zéro après un remboursement complet
refunded_amount decimal string Montant restitué à partir du débit initial ; égal au débit initial en cas de remboursement complet.
initial_quota_units integer Unités de compte exactes débitées initialement ; zéro pour les devis.
final_quota_units integer ou null Unités de compte exactes du coût net final ; null en attente, zéro après un remboursement complet.
account_unit_usd decimal string "0.000002" par unité de compte
media_charges object image, audio, other_reference sont à zéro selon le tarif actuel ; input_video_unrounded et output_video_unrounded séparent les composantes vidéo avant l'arrondi monétaire final
final_debit_may_exceed_estimate boolean true ; l'estimation n'est pas un plafond de dépenses strict
created_at integer Horodatage de création du détail de facturation en secondes Unix.
settled_at integer ou null Horodatage du règlement ou du remboursement final en secondes Unix ; null jusqu'à la finalisation.
Champ Type Signification
rounding.input_video string ceil_each_file_then_sum : arrondir chaque fichier d'entrée à l'entier supérieur, puis additionner.
rounding.output_video string nearest_integer_half_up : seconde de sortie la plus proche, les demi-secondes étant arrondies à l'entier supérieur.
rounding.effective_unit_rate string nearest_decimal_12_places_half_up : arrondir le taux effectif à 12 décimales.
rounding.money string nearest_account_unit_half_up : arrondir le montant combiné aux unités de compte.
rounding.amount_formula string Formule du montant combiné final ; les montants d'entrée et de sortie ne sont pas arrondis séparément.
media_charges.input_video_unrounded decimal string Composante vidéo d'entrée avant l'arrondi monétaire.
media_charges.output_video_unrounded decimal string Composante vidéo de sortie avant l'arrondi monétaire.
media_charges.image decimal string Supplément image séparé, actuellement zéro.
media_charges.audio decimal string Supplément audio séparé, actuellement zéro.
media_charges.other_reference decimal string Supplément pour autre référence, actuellement zéro.

Recalculer le coût final

Avec une vidéo de référence, le palier d'entrée vidéo s'applique à la fois aux secondes de sortie et aux secondes de la vidéo de référence. Les images et l'audio n'ont pas de supplément séparé selon le tarif Seedance actuel. Les nombres de tokens et le coût du fournisseur ne sont pas des entrées de facturation.

  1. Arrondir à l'entier supérieur la durée mesurée de chaque vidéo d'entrée indépendamment, puis additionner : input_seconds = sum(ceil(each_video_duration)).
  2. Arrondir la durée de sortie à la seconde entière la plus proche, les demi-secondes positives étant arrondies à l'entier supérieur.
  3. Additionner les secondes facturables d'entrée et de sortie.
  4. Multiplier par effective_unit_rate, diviser par account_unit_usd, puis arrondir le total une seule fois à l'unité de compte entière la plus proche, les demi-unités positives étant arrondies à l'entier supérieur.
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

Utilisez l'arithmétique décimale. N'arrondissez pas séparément les composantes monétaires d'entrée et de sortie. Par exemple, une tâche Seedance 2.0 de 4 secondes en 480P, sans vidéo de référence, avec un tarif de base 0.07031, un multiplicateur de canal 1 et un multiplicateur de compte 1.05, a un taux effectif de 0.0738255 et un coût net de 0.295302 USD (147651 unités de compte).

APIMaster mesure la durée de la vidéo de référence plutôt que de faire confiance aux champs client tels que input_seconds ou reference_seconds. La duration/seconds demandée contrôle la durée de sortie. Pour les sorties, le règlement privilégie la durée signalée par le fournisseur et détecte la sortie si nécessaire ; les mesures indisponibles peuvent être remplacées par les secondes facturables du fournisseur ou la durée demandée/réservée. Le reçu étiquette explicitement la source. Une valeur de repli n'est jamais étiquetée comme une durée réelle mesurée indépendamment. Les actifs en cache existants ou les anciens brouillons hérités peuvent manquer de détails complets de mesure par fichier.

actual_time dans la réponse vidéo est le temps de traitement de la tâche, pas la durée de la vidéo de sortie. usage.completion_tokens, lorsqu'il est présent, est informatif.

Échecs et remboursements

Les échecs de tâche du fournisseur et le délai d'expiration configuré de 24 heures pour les tâches inachevées déclenchent un remboursement complet automatique. Leurs reçus restent récupérables et affichent refunded avec un montant net nul une fois le remboursement réussi. Les erreurs temporaires d'interrogation/réseau ne remboursent ni n'annulent immédiatement une tâche ; le traitement est réessayé.

Un échec de soumission confirmé comme non facturé est remboursé. Un résultat de soumission ambigu est conservé pour un rapprochement automatique (premier rapprochement asynchrone après environ 20 minutes ; les résultats toujours inconnus après 24 heures sont remboursés lors du rapprochement). Si la soumission n'a pas créé de tâche publique, il n'existe aucun reçu lié à une tâche pour cette tentative. Un devis n'est pas une réservation et ne nécessite aucune libération.

Il n'existe aucun point de terminaison public d'annulation Seedance. Se déconnecter ou arrêter l'interrogation n'annule pas une tâche. Les vérifications de l'état des tâches empêchent l'interrogation répétée d'appliquer à nouveau le même règlement/remboursement d'achèvement, tandis que le point de terminaison de reçu lui-même est en lecture seule. Ce ne sont pas des garanties exactement-une-fois générales pour chaque défaillance d'infrastructure ; les opérations financières en attente ne doivent pas être traitées comme finalisées.

Seedance : idempotence et récupération des soumissions