Saltar a la navegación

Exporta el uso y los costes

Usa Enumerar los costes de generación para consultar cuánto costaron tus generaciones en un intervalo de tiempo, por ejemplo para importar los datos cada día a un almacén de datos. Devuelve un elemento por generación finalizada, con hasta 500 por llamada. Un día con 8,000 generaciones requiere 16 solicitudes.

Para consultar el coste de una sola generación, usa Obtener los costes de generación. Ambos endpoints devuelven el mismo objeto de coste.

Solicita un intervalo de tiempo

Envía startTime y endTime como fechas y horas UTC en formato ISO 8601. El intervalo filtra por el momento en que terminó la generación. startTime está incluido y endTime queda excluido.

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'
ParámetroDescripción
startTimeObligatorio. Inicio del intervalo, incluido.
endTimeObligatorio. Fin del intervalo, excluido. Debe ser posterior a startTime.
limitElementos por página, de 1 a 500. El valor predeterminado es 100.
cursorEl nextCursor de la página anterior. Envíalo con los mismos valores de startTime y endTime.

Una clave de API enumera todas las generaciones de su organización, con independencia de la clave o del miembro de Studio que las creó.

Lee todas las páginas

La respuesta es { "items": [...], "nextCursor": "..." }. Solicita la página siguiente con los mismos valores de startTime y endTime y añade cursor. Repite hasta que nextCursor sea null. Los elementos se ordenan del más antiguo al más reciente.

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

Mantén startTime y endTime fijos al recorrer las páginas. El cursor continúa desde una generación del intervalo, así que cambiar el intervalo entre páginas puede omitir elementos. Si el cursor no corresponde a una generación del intervalo solicitado, se devuelve 400 para distinguir ese caso del fin de los datos.

Qué contiene cada elemento

DatoCampo
ID de generacióngenerationId
HoracreatedAt, finishedAt
Modelomodel
EstadogenerationStatus
Cantidad facturadacomponents[].quantity con components[].unit (frames para sincronización labial y seconds para doblaje y voz)
Coste en USDtotalCostUsd, con cada parte en components[].amountUsd
Tu tarifacomponents[].unitRateUsd
Clave de APIapiKey.name y apiKey.mask (los primeros y últimos caracteres de la clave, como se muestran en Studio), además de apiKey.id. apiKey es null para una generación creada en 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"
}

Los importes son cadenas de números decimales con cinco cifras decimales. Interprétalos como valores decimales y evita usar números de coma flotante. Una generación con doblaje o voz generada tiene un componente por cada parte.

Configura una extracción diaria

  • Usa intervalos consecutivos. Cada generación aparece en un solo intervalo, aquel en el que terminó. Los intervalos como los días UTC nunca se solapan ni omiten generaciones.
  • Espera 10 minutos después de que termine el intervalo. Los costes suelen registrarse en unos 10 minutos desde que termina la generación. Hasta entonces, un elemento puede tener availability: "pending". Vuelve a leer el intervalo más tarde para recoger los importes registrados desde la última lectura.
  • Usa generationId como clave de cada fila. Volver a leer un intervalo devuelve las mismas generaciones. Inserta las filas nuevas y actualiza las existentes para mantener la tabla al día.
  • Interpreta null como un valor desconocido, nunca como cero. totalCostUsd es null si se desconoce alguna parte del coste. knownSubtotalUsd es la parte conocida. Consulta Disponibilidad.
  • La lista solo incluye generaciones finalizadas. Una generación en curso aparece en el intervalo en el que termina.

Disponibilidad

availability indica qué parte del coste de un elemento se conoce. status y reason de cada componente indican por qué falta un importe.

availabilitySignificado
completeTodos los componentes tienen un importe. totalCostUsd tiene un valor.
pendingAún no se conoce ningún importe y queda al menos uno por registrar. Vuelve a leer el elemento más tarde.
partialAlgunos componentes tienen un importe y otros todavía carecen de él. totalCostUsd es null. knownSubtotalUsd es la suma de los importes conocidos. Un componente que falta puede estar pendiente o carecer de registro, como la voz generada que no se desglosa por generación.
unavailableNo hay importes conocidos ni pendientes. Una generación fallida o rechazada no se cobra y normalmente carece de un coste registrado.

Un componente pending suele recibir su importe en unos 10 minutos, aunque no hay garantía de que un elemento pase a complete. Los elementos partial y unavailable pueden conservar ese estado.

En los planes de créditos, los importes reflejan el valor nominal de $0.01 por crédito, que puede diferir del precio pagado por los créditos. Los importes excluyen impuestos, cuotas de suscripción, reembolsos, créditos de la cuenta y cargos de proveedores externos.

Gestiona los errores

EstadoSignificadoQué hacer
400Fecha y hora ausentes o inválidas, intervalo vacío, limit fuera del rango de 1 a 500 o cursor que no corresponde a una generación del intervalo solicitado.Corrige la solicitud.
401Clave de API ausente o inválida.Consulta Autenticación.
503 usage_dependency_unavailableNo se pudo leer el uso registrado. Falla toda la página y no se devuelve una página parcial.Reintenta la misma solicitud.

Todas las solicitudes son de lectura, así que puedes volver a solicitar cualquier página con seguridad.