Zur Navigation springen

Nutzung und Kosten exportieren

Mit List Generation Costs rufst du die Kosten deiner Generierungen für einen Zeitraum ab, etwa für einen täglichen Import in ein Data Warehouse. Der Endpunkt liefert einen Eintrag pro abgeschlossener Generierung und bis zu 500 Einträge pro Aufruf. Für einen Tag mit 8,000 Generierungen brauchst du daher 16 Anfragen.

Verwende Get Generation Costs, um die Kosten einer einzelnen Generierung abzurufen. Beide Endpunkte liefern dasselbe Kostenobjekt.

Einen Zeitraum abfragen

Sende startTime und endTime als UTC-Zeitstempel nach ISO 8601. Der Zeitraum filtert nach dem Zeitpunkt, zu dem eine Generierung abgeschlossen wurde. startTime ist inklusive und endTime exklusive.

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'
ParameterBeschreibung
startTimeErforderlich. Beginn des Zeitraums, inklusive.
endTimeErforderlich. Ende des Zeitraums, exklusive. Muss nach startTime liegen.
limitEinträge pro Seite, 1 bis 500. Standardmäßig 100.
cursorDer Wert von nextCursor aus der vorherigen Seite. Sende ihn mit denselben Werten für startTime und endTime.

Mit einem API-Schlüssel kannst du alle Generierungen seiner Organisation auflisten. Es spielt keine Rolle, welcher Schlüssel oder welches Studio-Mitglied sie erstellt hat.

Alle Seiten abrufen

Die Antwort lautet { "items": [...], "nextCursor": "..." }. Fordere mit denselben Werten für startTime und endTime sowie mit cursor die nächste Seite an, bis nextCursor den Wert null hat. Die ältesten Einträge stehen zuerst.

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"])

Lass startTime und endTime beim Abrufen weiterer Seiten unverändert. Der Cursor setzt bei einer Generierung innerhalb des Zeitraums an. Wenn du den Zeitraum zwischen Seiten änderst, kannst du Einträge überspringen. Wenn der Cursor nicht auf eine Generierung im angefragten Zeitraum verweist, meldet die API 400. So lässt sich der Fehler vom Ende der Liste unterscheiden.

Angaben pro Eintrag

AngabeFeld
Generierungs-IDgenerationId
ZeitcreatedAt, finishedAt
Modellmodel
StatusgenerationStatus
Abgerechnete Mengecomponents[].quantity mit components[].unit (frames für Lip Sync, seconds für Dubbing und Sprache)
Kosten in USDtotalCostUsd und die einzelnen Beträge in components[].amountUsd
Dein Preis pro Einheitcomponents[].unitRateUsd
API-SchlüsselapiKey.name und apiKey.mask (die ersten und letzten Zeichen des Schlüssels wie in Studio angezeigt) sowie apiKey.id. Bei einer in Studio erstellten Generierung ist apiKey gleich null.
{
"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"
}

Beträge sind Zeichenfolgen mit fünf Dezimalstellen. Lies sie als Dezimalzahlen ein und vermeide Gleitkommazahlen. Eine Generierung mit Dubbing oder erzeugter Sprache enthält eine Komponente pro Bestandteil.

Einen täglichen Abruf einrichten

  • Verwende lückenlos aufeinanderfolgende Zeiträume. Jede Generierung erscheint genau in dem Zeitraum, in dem sie abgeschlossen wurde. Wenn du zum Beispiel einen Zeitraum pro UTC-Tag verwendest, überschneiden sich die Zeiträume nie und keine Generierung wird übersprungen.
  • Warte nach dem Ende des Zeitraums 10 Minuten. Kosten werden normalerweise innerhalb von etwa 10 Minuten nach Abschluss erfasst. Davor kann ein Eintrag availability: "pending" haben. Rufe den Zeitraum später erneut ab, um inzwischen erfasste Beträge zu übernehmen.
  • Verwende generationId als Zeilenschlüssel. Ein erneuter Abruf desselben Zeitraums liefert dieselben Generierungen. Füge neue Zeilen ein und aktualisiere bestehende, damit deine Tabelle korrekt bleibt.
  • Behandle null als unbekannten Wert. totalCostUsd ist null, sofern nicht alle Kostenbestandteile bekannt sind. knownSubtotalUsd enthält den bekannten Teil. Siehe Verfügbarkeit.
  • Die Liste enthält nur abgeschlossene Generierungen. Eine laufende Generierung erscheint im Zeitraum, in dem sie abgeschlossen wird.

Verfügbarkeit

availability gibt an, wie viel von den Kosten eines Eintrags bekannt ist. status und reason der einzelnen Komponenten geben an, warum ein Betrag fehlt.

availabilityBedeutung
completeFür jede Komponente liegt ein Betrag vor. totalCostUsd ist gesetzt.
pendingEs ist noch kein Betrag bekannt und mindestens einer wird noch erfasst. Rufe den Eintrag später erneut ab.
partialFür einige Komponenten liegt ein Betrag vor. totalCostUsd ist null und knownSubtotalUsd ist die Summe der bekannten Beträge. Bei einer fehlenden Komponente kann die Erfassung noch ausstehen oder es gibt keinen Datensatz, etwa wenn erzeugte Sprache nicht pro Generierung aufgeschlüsselt wird.
unavailableEs ist kein Betrag bekannt und keiner steht aus. Fehlgeschlagene oder abgelehnte Generierungen werden nicht berechnet und haben normalerweise keinen Kosteneintrag.

Bei einer Komponente mit pending liegt der Betrag meist innerhalb von etwa 10 Minuten vor. Es gibt jedoch keine Garantie, dass der Eintrag complete wird. Einträge mit partial oder unavailable können diesen Status behalten.

Bei Credit-Tarifen entsprechen die Beträge dem Nennwert von $0.01 pro Credit. Dieser Wert kann vom tatsächlich gezahlten Preis abweichen. Steuern, Abogebühren, Erstattungen, Kontoguthaben und Gebühren externer Anbieter sind in den Beträgen nicht enthalten.

Fehler behandeln

StatusBedeutungWas du tun kannst
400Ein fehlender oder ungültiger Zeitstempel, ein leerer Zeitraum, ein limit außerhalb von 1 bis 500 oder ein cursor, der auf keine Generierung im angefragten Zeitraum verweist.Korrigiere die Anfrage.
401Der API-Schlüssel fehlt oder ist ungültig.Siehe Authentifizierung.
503 usage_dependency_unavailableDie erfasste Nutzung ließ sich nicht lesen. Die gesamte Seite schlägt fehl und es wird keine unvollständige Seite zurückgegeben.Wiederhole dieselbe Anfrage.

Jede Anfrage liest Daten. Du kannst den Abruf jeder Seite gefahrlos wiederholen.