Passer à la navigation

Exporter l’utilisation et les coûts

Utilisez Lister les coûts des générations pour récupérer le coût de vos générations sur une période, par exemple pour alimenter chaque jour un entrepôt de données. L’API renvoie un élément par génération terminée et jusqu’à 500 par appel. Il faut donc 16 requêtes pour une journée de 8,000 générations.

Pour connaître le coût d’une seule génération, utilisez Récupérer les coûts d’une génération. Les deux points de terminaison renvoient le même objet de coût.

Interroger une période

Envoyez startTime et endTime sous forme de dates et heures UTC au format ISO 8601. Le filtre porte sur la date de fin de la génération. La borne startTime est incluse et la borne endTime est exclue.

curl --fail-with-body --silent --show-error --get \
'https://api.sync.so/v2/usage/generations' \
--header "x-api-key: $SYNC_API_KEY" \
--data-urlencode 'startTime=2026-11-12T00:00:00Z' \
--data-urlencode 'endTime=2026-11-13T00:00:00Z' \
--data-urlencode 'limit=500'
ParamètreDescription
startTimeObligatoire. Début inclus de la période.
endTimeObligatoire. Fin exclue de la période. Doit être postérieure à startTime.
limitÉléments par page, de 1 à 500. La valeur par défaut est 100.
cursorLe nextCursor de la page précédente. Envoyez-le avec les mêmes valeurs de startTime et endTime.

Une clé API permet de lister toutes les générations de son organisation, quelle que soit la clé ou la personne qui les a créées dans Studio.

Lire toutes les pages

La réponse est { "items": [...], "nextCursor": "..." }. Demandez la page suivante avec les mêmes valeurs de startTime et endTime, ainsi que cursor, jusqu’à ce que nextCursor vaille null. Les éléments sont triés du plus ancien au plus récent.

import os
import requests
def generation_costs(start_time: str, end_time: str):
params = {"startTime": start_time, "endTime": end_time, "limit": 500}
while True:
response = requests.get(
"https://api.sync.so/v2/usage/generations",
headers={"x-api-key": os.environ["SYNC_API_KEY"]},
params=params,
timeout=60,
)
response.raise_for_status()
page = response.json()
yield from page["items"]
if page["nextCursor"] is None:
return
params["cursor"] = page["nextCursor"]
for item in generation_costs("2026-11-12T00:00:00Z", "2026-11-13T00:00:00Z"):
print(item["generationId"], item["finishedAt"], item["model"], item["totalCostUsd"])

Conservez les valeurs de startTime et endTime pendant la pagination. Le curseur reprend à partir d’une génération de la période. Changer de période entre deux pages peut donc omettre des éléments. Si le curseur ne correspond à aucune génération de la période demandée, l’API renvoie 400 pour distinguer cette erreur de la fin des données.

Contenu de chaque élément

DonnéeChamp
Identifiant de générationgenerationId
Date et heurecreatedAt, finishedAt
Modèlemodel
ÉtatgenerationStatus
Quantité facturéecomponents[].quantity avec components[].unit (frames pour la synchronisation labiale, seconds pour le doublage et la synthèse vocale)
Coût en USDtotalCostUsd, avec le détail dans components[].amountUsd
Votre tarifcomponents[].unitRateUsd
Clé APIapiKey.name et apiKey.mask (les premiers et derniers caractères de la clé, tels qu’affichés dans Studio), ainsi que apiKey.id. apiKey vaut null pour une génération créée dans Studio.
{
"items": [
{
"generationId": "6bb46001-dd37-4f4d-908a-54bd67c4dc55",
"generationStatus": "COMPLETED",
"currency": "USD",
"availability": "complete",
"totalCostUsd": "0.79950",
"knownSubtotalUsd": "0.79950",
"retryAfterSeconds": null,
"components": [
{
"type": "lipsync",
"operationId": "6bb46001-dd37-4f4d-908a-54bd67c4dc55",
"status": "recorded",
"amountUsd": "0.79950",
"credits": null,
"valueBasis": "metered_usage",
"quantity": 150,
"unit": "frames",
"unitRateUsd": "0.00533",
"source": "recorded_usage",
"reason": null
}
],
"excludedCosts": [
"tax",
"subscription_fees",
"external_provider_charges",
"account_level_adjustments"
],
"createdAt": "2026-11-12T08:14:03.120Z",
"finishedAt": "2026-11-12T08:15:41.007Z",
"model": "sync-3",
"apiKey": {
"id": "6f4e5e34-399e-4e0d-82a2-f624a6ba9fd8",
"name": "production",
"mask": "sk-AB...wxyz"
}
}
],
"nextCursor": "0d7f5b4e-2a1c-4c3e-9b8a-7e6d5c4b3a21"
}

Les montants sont des chaînes représentant des nombres à cinq décimales. Analysez-les comme des nombres décimaux et excluez les nombres à virgule flottante. Une génération avec doublage ou synthèse vocale contient une composante pour chaque prestation.

Mettre en place un export quotidien

  • Utilisez des périodes consécutives. Une génération apparaît dans une seule période, celle où elle s’est terminée. Les périodes définies par jour UTC, par exemple, ne se chevauchent pas et n’omettent aucune génération.
  • Attendez 10 minutes après la fin de la période. L’enregistrement des coûts prend généralement environ 10 minutes après la fin de la génération. Avant cela, un élément peut avoir availability: "pending". Interrogez à nouveau la période plus tard pour récupérer les montants enregistrés depuis.
  • Utilisez generationId comme clé de ligne. Relire une période renvoie les mêmes générations. Insérez ou mettez à jour les lignes selon leur clé pour garder votre table à jour.
  • Interprétez null comme un montant inconnu. totalCostUsd vaut null tant que toutes les composantes du coût ne sont pas connues. knownSubtotalUsd indique la part connue. Consultez Disponibilité.
  • La liste contient uniquement les générations terminées. Une génération en cours apparaît dans la période où elle se termine.

Disponibilité

availability indique la part connue du coût d’un élément. Les champs status et reason de chaque composante indiquent pourquoi un montant manque.

availabilitySignification
completeToutes les composantes ont un montant. totalCostUsd est renseigné.
pendingAucun montant n’est encore connu et au moins un montant est en cours d’enregistrement. Relisez l’élément plus tard.
partialCertaines composantes ont un montant et d’autres non. totalCostUsd vaut null et knownSubtotalUsd est la somme des montants connus. Une composante manquante peut être en cours d’enregistrement ou sans montant enregistré, par exemple si la synthèse vocale n’est pas détaillée par génération.
unavailableAucun montant n’est connu ni en cours d’enregistrement. Une génération qui échoue ou est rejetée n’est pas facturée et n’a généralement aucun coût enregistré.

Le montant d’une composante pending est généralement renseigné dans un délai d’environ 10 minutes. Rien ne garantit qu’un élément passera à complete. Les éléments partial et unavailable peuvent conserver cet état.

Avec les forfaits à crédits, les montants correspondent à la valeur nominale de $0.01 par crédit. Cette valeur peut différer du prix payé. Les montants excluent les taxes, les frais d’abonnement, les remboursements, les avoirs et les frais des prestataires externes.

Gérer les erreurs

StatutSignificationAction
400Une date ou heure manquante ou invalide, une période vide, un limit hors de l’intervalle de 1 à 500 ou un cursor qui ne correspond à aucune génération de la période demandée.Corrigez la requête.
401Clé API manquante ou invalide.Consultez Authentification.
503 usage_dependency_unavailableImpossible de lire l’utilisation enregistrée. La requête échoue pour la page entière. Elle ne renvoie aucune page partielle.Réessayez avec la même requête.

Toutes les requêtes sont en lecture seule. Vous pouvez donc réessayer de récupérer n’importe quelle page sans risque.