Ir para a navegação

Exportar uso e custos

Use Custos de Geração de Listas Para carregar o que suas gerações custam ao longo de um intervalo de tempo, por exemplo, um diariamente puxar em um depósito de dados. 500 Por chamada, então um dia com 8,000 As gerações são 16 Pedidos.

Para o custo de uma única geração, use Obter Custos de Geração. Ambos os endpoints retornam o mesmo objeto de custo.

Solicitar um intervalo de tempo

Envie startTime e endTime como datas-hora ISO 8601 UTC. O intervalo filtra pelo momento em que uma geração concluiu. startTime é inclusivo e endTime é exclusivo.

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âmetroDescrição
startTimeObrigatório. Início do intervalo, inclusivo.
endTimeObrigatório. Fim do intervalo, exclusivo. Deve ser após startTime.
limitNúmero de itens por página, de 1 a 500. Padrão é 100.
cursorO nextCursor da página anterior. Envie com o mesmo startTime e endTime.

Uma chave de API lista todas as gerações da organização, independentemente de qual chave ou membro do Studio as criou.

Leia todas as páginas

A resposta é { "items": [...], "nextCursor": "..." }. Solicite a próxima página com o mesmo startTime e endTime mais cursor, até que nextCursor seja null. Os itens estão ordenados do mais antigo para o mais recente.

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

Mantenha startTime e endTime ao consultar as páginas seguintes. O cursor retoma a consulta a partir de uma geração do intervalo. Alterar o intervalo entre páginas pode fazer com que alguns itens sejam ignorados. Se o cursor não corresponder a uma geração do intervalo solicitado, a API retorna 400, o que diferencia esse erro do fim dos resultados.

O que cada item contém

O que você precisaCampo
ID da geraçãogenerationId
TempocreatedAt, finishedAt
Modelomodel
StatusgenerationStatus
Quantidade cobradacomponents[].quantity com components[].unit (frames para sincronização labial, seconds para dublagem e falas)
Custo em USDtotalCostUsd, com cada parte em components[].amountUsd
Sua taxacomponents[].unitRateUsd
Chave APIapiKey.name e apiKey.mask (os primeiros e os últimos caracteres da chave, como exibidos no Studio), além de apiKey.id. apiKey é null para uma geração criada no 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"
}

Os valores são strings decimais com cinco casas decimais. Analisá-los como decimais, não como flutuantes. Uma geração com dublagem ou com texto gerado tem um componente para cada parte.

Crie uma extração diária

  • Use faixas consecutivas. Uma geração aparece exatamente em uma faixa, a faixa em que ela foi concluída. As faixas, como uma por dia UTC, nunca se sobrepõem e nunca deixam de incluir uma geração.
  • Espere 10 minutos após o fim do intervalo. Os custos são normalmente registrados dentro de cerca de 10 minutos após a conclusão. Antes disso, um item pode ter availability: "pending". Leia o intervalo novamente mais tarde para capturar as quantias registradas desde então.
  • Use generationId como chave para suas linhas. Ao ler uma faixa novamente, você recebe as mesmas gerações, então uma atualização de inserção garante que sua tabela esteja correta.
  • Trate null como desconhecido, não como zero. totalCostUsd é null a menos que todos os componentes do custo sejam conhecidos. knownSubtotalUsd é a parte conhecida. Veja disponibilidade.
  • Somente as gerações concluídas são listadas. Uma geração em progresso aparece na faixa em que ela é concluída.

Disponibilidade

availability diz quantas partes do custo de um item são conhecidas. Cada componente tem status e reason que explicam por que uma quantia está faltando.

availabilitySignificado
completeCada componente tem uma quantidade. totalCostUsd está definido.
pendingNenhuma quantidade é conhecida ainda e pelo menos uma está sendo registrada. Leia o item novamente mais tarde.
partialAlguns componentes têm uma quantidade e outros não. totalCostUsd é null; knownSubtotalUsd é a soma das conhecidas. Um componente ausente pode estar pendente ou não ter registro, por exemplo, uma geração de áudio que não é itemizada por geração.
unavailableNão se conhece nenhuma quantidade e nenhum está pendente. Uma geração falhada ou rejeitada não é cobrada e normalmente não tem registro de custo.

Um componente pending geralmente recebe sua quantidade dentro de cerca de 10 minutos, mas um item não está garantido a se tornar complete. Itens partial e unavailable podem permanecer assim.

Nos planos de crédito, os valores são o valor nominal dos créditos da $0.01 cada, que pode diferir do preço pago em dinheiro por esses créditos.

Tratar erros

StatusSignificadoO que fazer
400Uma data-hora ausente ou inválida, um intervalo vazio, um limit fora do intervalo de 1 a 500, ou um cursor que não é uma geração no intervalo solicitado.Corrija a solicitação.
401Chave API ausente ou inválida.Ver Autenticação.
503 usage_dependency_unavailableO uso registrado não pode ser lido. A página falha como um todo; nenhuma página parcial é retornada.Tente a mesma solicitação novamente.

Todo pedido é uma leitura, então qualquer página pode ser reenviada.