APIMaster.ai

Cotações e recibos de cobrança do Seedance

Estime os custos de geração do Seedance e verifique o débito final usando recibos de cobrança autenticados e persistentes.

Cotações e recibos de cobrança do Seedance

Aplica-se a seedance-2.0, seedance-2.5, seedance-2.0-fast e seedance-2.0-mini, em todos os canais de geração. URL base: https://apimaster.ai/v1 (https://apimaster.ai/v1). Autentique todas as requisições com Authorization: Bearer YOUR_API_KEY.

Obter uma estimativa

POST https://apimaster.ai/v1/videos/quote aceita os mesmos parâmetros JSON de uma requisição padrão de geração de vídeo, incluindo model, prompt, duration, resolution, video_urls e outras configurações de geração suportadas. Geração de rascunho, upgrades de rascunho e cotações de remix não são suportados no momento.

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}'

A resposta contém object: "video.quote", quote_id, expires_at (segundos Unix), binding: false, funds_reserved: false e um objeto billing descrito abaixo. A cotação tem um período de validade consultivo de cinco minutos. Ela não debita fundos, não cria uma tarefa nem inicia a geração no provedor. Portanto, billing.reserved_amount é "0.000000". O ID da cotação é informativo; não é um token de autorização ou de travamento de preço e não precisa ser enviado com a geração.

O preço é recalculado no momento do envio real e congelado para essa tarefa. Uma estimativa não é uma garantia de cobrança máxima. A tarefa concluída pode custar mais ou menos que a estimativa. Requisições com duração automática usam uma estimativa de saída de 30 segundos; requested_output_seconds é -1.

A geração permanece sujeita à validação do provedor. Para requisições de extensão de vídeo do Seedance 2.5, defina explicitamente aspect_ratio: "adaptive"; uma rejeição do provedor é tratada pelo ciclo de vida normal de reembolso.

Recuperar o recibo da tarefa

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

GET /v1/videos/{task_id}/billing retorna object: "video.billing_receipt", billing e customer_billing. Use uma chave de API da conta proprietária da tarefa. Com a chave original, GET /v1/video-submissions/by-key exibe a cobrança do cliente em data.customer_billing. Se final: true, net_amount é a cobrança líquida definitiva, representada como texto decimal em USD. Uma tarefa antiga com reembolso confirmado pode exibir cobrança líquida zero mesmo sem confirmação da cobrança do provedor. A consulta por ID de tarefa retorna HTTP 404 se a tarefa pertencer a outra conta ou se não houver recibo nem evidência de reembolso. Consulte os campos de nova tentativa para saber se é seguro reenviar.

O mesmo objeto billing está incluído em ambas as respostas de consulta de tarefa:

  • GET /v1/videos/{task_id}: billing no nível superior.
  • GET /v1/video/generations/{task_id}: data.billing.

settlement_status é pending, settled ou refunded; respostas de cotação usam estimate. A conclusão da tarefa e a liquidação financeira são separadas: trate os valores como finais apenas quando o recibo estiver settled ou refunded. Requisições repetidas de recibo não executam geração, liquidação ou reembolsos. Recibos finalizados mantêm o mesmo ID de recibo e conteúdo, inclusive após um reembolso.

Exemplos completos de requisição e resposta

Ambos os exemplos usam Seedance 2.0 em 480P, uma saída solicitada de 4 segundos, uma referência medida em 4,042 segundos, multiplicador de canal 1 e multiplicador de conta 1,05. As durações e valores de conclusão vêm de um teste real; a cotação é um exemplo ilustrativo montado para entradas correspondentes. IDs e URLs de mídia são placeholders. As taxas reais vêm da sua resposta da API.

1. Obter uma cotação

POST https://apimaster.ai/v1/videos/quote, JSON da requisição:

{
  "model": "seedance-2.0",
  "prompt": "A paper boat moves gently on a pond.",
  "duration": 4,
  "resolution": "480p",
  "video_urls": [
    "https://example.com/reference.mp4"
  ]
}
Campo Tipo Significado
model string ID do modelo, seedance-2.0 aqui.
prompt string Prompt de geração.
duration integer Segundos de saída solicitados, não a duração do vídeo de referência.
resolution string Resolução de saída, 480p aqui.
video_urls array URLs dos vídeos de referência. Substitua o placeholder por mídia acessível; o servidor mede cada arquivo.

Resposta da cotação:

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

A entrada de 4,042 segundos é arredondada para cima, para 5 segundos. Com 4 segundos de saída estimados, a estimativa cobre 9 segundos e custa 0,408146 USD. A cotação não debita fundos; os valores finais permanecem nulos.

2. Enviar a geração e consultar a conclusão

Após enviar para POST https://apimaster.ai/v1/videos/generations, a resposta inicial contém o ID da tarefa:

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

Em seguida, consulte GET https://apimaster.ai/v1/videos/task_example usando uma chave de API da mesma conta. Após a geração e a liquidação terminarem:

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

O débito inicial é igual ao custo final aqui, sem débito adicional ou reembolso. billing.output.actual_seconds é a duração da saída; actual_time é o tempo de processamento. usage.completion_tokens não determina a cobrança. Campos opcionais podem variar conforme o canal.

GET https://apimaster.ai/v1/videos/task_example/billing retorna { "object": "video.billing_receipt", "billing": ... } com o mesmo objeto billing. A consulta de compatibilidade GET https://apimaster.ai/v1/video/generations/task_example o coloca em data.billing.

Campos externos da resposta

Campo Tipo Significado
object string Tipo de resposta: video.quote, video ou video.billing_receipt.
quote_id string Identificador informativo da cotação; não é um travamento de preço nem uma autorização de geração.
expires_at integer Expiração consultiva da cotação em segundos Unix, normalmente a criação mais 300 segundos.
binding boolean Atualmente false; a cotação não garante um valor final.
funds_reserved boolean Atualmente false; a cotação não debita nem reserva fundos.
billing object Detalhes de cobrança documentados individualmente abaixo.
code integer Código de resposta do envio; 200 significa enviado, não concluído.
data array Lista de tarefas enviadas; a consulta de compatibilidade, em vez disso, usa um objeto para data.
data[].status string Status do envio, submitted neste exemplo.
data[].task_id string Identificador público da tarefa usado em consultas subsequentes.
id string ID público da tarefa na consulta de conclusão.
task_id string Identificador da tarefa, igual a id neste exemplo.
model string Nome público do modelo de geração.
status string Status da tarefa; completed significa que a geração terminou. Verifique billing.settlement_status para a liquidação final.
progress number Percentual de progresso; 100 na conclusão neste exemplo.
actual_time number Segundos de processamento da tarefa, não a duração do vídeo de saída.
created_at integer Timestamp de criação da tarefa em segundos Unix.
completed_at integer Timestamp de conclusão da tarefa em segundos Unix.
metadata object Metadados do resultado da geração.
metadata.url string URL de download do conteúdo do vídeo.
usage object Informações de uso do provedor; pode estar ausente dependendo do canal.
usage.completion_tokens integer Contagem de tokens do provedor; não usada para cobrança por segundo desses quatro modelos.

Esquema de cobrança

Todos os valores monetários e taxas unitárias são strings decimais. As durações de tempo são em segundos. Campos anuláveis são null em JSON até estarem disponíveis.

Campo Tipo Significado
schema_version string Versão do esquema de cobrança, "1" neste exemplo.
receipt_id string Identificador estável do recibo; ausente nas cotações.
task_id string ID público da tarefa vinculado ao recibo; ausente nas cotações.
settlement_status string estimate, pending, settled, refunded
model string ID público do modelo aplicado.
resolution string Resolução normalizada usada para cobrança.
tariff_variant string Nível tarifário; -input indica vídeos de referência, com esta taxa aplicando-se à entrada e à saída.
tariff_revision string Impressão digital do modelo, nível tarifário, taxa base configurada e versão das regras de cobrança
currency string Moeda da cobrança, atualmente USD.
unit string Unidade da taxa; second significa por segundo.
base_unit_rate decimal string Preço base configurado por segundo para este modelo e nível.
channel_multiplier number Multiplicador agregado de preço do canal aplicado.
account_multiplier number Multiplicador de conta/grupo aplicado, 1,05 neste exemplo.
effective_unit_rate decimal string Taxa por segundo aplicada, congelada no envio e arredondada para 12 casas decimais.
requested_output_seconds integer Duração de saída solicitada; -1 para duração automática
estimated_output_seconds integer Segundos de saída estimados; a duração automática é estimada em 30 segundos.
estimated_billable_seconds integer Total inicial estimado de segundos faturáveis, incluindo vídeos de referência e saída estimada.
input_videos array Medições do servidor por referência, na ordem da requisição
input_videos[].index integer Posição do vídeo de referência na requisição, começando em zero.
input_videos[].media_id string Hash de mídia com escopo de conta ou ID de ativo próprio; nenhuma URL de vídeo de referência é ecoada.
input_videos[].measured_seconds number ou null Duração medida pelo servidor antes do arredondamento; pode ser null para ativos em cache mais antigos
input_videos[].billable_seconds integer Duração faturável arredondada desta referência
input_videos[].duration_source string apimaster_probe ou apimaster_asset_cache
billable_input_video_seconds integer Soma dos segundos faturáveis por referência
output object ou null Informações da duração final da saída, disponíveis após liquidação bem-sucedida
output.actual_seconds number ou null Duração real da saída reportada/sondada; null se indisponível
output.billable_seconds integer Segundos de saída efetivamente usados na liquidação
output.duration_source string provider_reported, apimaster_probe, provider_billable_seconds, requested_duration_fallback ou reservation_fallback
billable_seconds integer ou null Segundos faturáveis finais combinados de entrada/saída
rounding object Regras de arredondamento de entrada, saída e valores monetários e fórmula do valor
estimated_amount decimal string Custo inicial estimado, não um valor final nem uma garantia de cobrança máxima.
reserved_amount decimal string Débito inicial da conta no envio, zero para cotações; não é uma retenção de autorização bancária.
additional_debit_amount decimal string Débito adicional quando o custo final excede o débito inicial.
final_debit_amount decimal string ou null Custo líquido final da tarefa após ajustes; zero após reembolso total
net_amount decimal string ou null Custo líquido final da tarefa após ajustes; zero após reembolso total
refunded_amount decimal string Valor devolvido do débito inicial; igual ao débito inicial em um reembolso total.
initial_quota_units integer Unidades exatas da conta debitadas inicialmente; zero para cotações.
final_quota_units integer ou null Unidades exatas da conta do custo líquido final; null enquanto pendente, zero após um reembolso total.
account_unit_usd decimal string "0.000002" por unidade de conta
media_charges object image, audio, other_reference são zero sob a tarifa atual; input_video_unrounded e output_video_unrounded separam os componentes de vídeo antes do arredondamento monetário final
final_debit_may_exceed_estimate boolean true; a estimativa não é um limite rígido de gastos
created_at integer Timestamp de criação do detalhe de cobrança em segundos Unix.
settled_at integer ou null Timestamp de liquidação final ou reembolso em segundos Unix; null até ser finalizado.
Campo Tipo Significado
rounding.input_video string ceil_each_file_then_sum: arredonda cada arquivo de entrada para cima e depois soma.
rounding.output_video string nearest_integer_half_up: segundo de saída mais próximo, meios segundos arredondados para cima.
rounding.effective_unit_rate string nearest_decimal_12_places_half_up: arredonda a taxa efetiva para 12 casas decimais.
rounding.money string nearest_account_unit_half_up: arredonda o valor combinado para unidades de conta.
rounding.amount_formula string Fórmula do valor combinado final; os valores de entrada e saída não são arredondados separadamente.
media_charges.input_video_unrounded decimal string Componente do vídeo de entrada antes do arredondamento monetário.
media_charges.output_video_unrounded decimal string Componente do vídeo de saída antes do arredondamento monetário.
media_charges.image decimal string Sobretaxa separada de imagem, atualmente zero.
media_charges.audio decimal string Sobretaxa separada de áudio, atualmente zero.
media_charges.other_reference decimal string Sobretaxa de outras referências, atualmente zero.

Recalcular o custo final

Com vídeo de referência, o nível de entrada de vídeo aplica-se tanto aos segundos de saída quanto aos segundos do vídeo de referência. Imagens e áudio não têm sobretaxa separada sob a tarifa atual do Seedance. Contagens de tokens e custo do provedor não são entradas de cobrança.

  1. Arredonde a duração medida de cada vídeo de entrada para cima independentemente e depois some: input_seconds = sum(ceil(each_video_duration)).
  2. Arredonde a duração de saída para o segundo inteiro mais próximo, com meios segundos positivos arredondados para cima.
  3. Some os segundos faturáveis de entrada e saída.
  4. Multiplique por effective_unit_rate, divida por account_unit_usd e então arredonde o total uma vez para a unidade de conta inteira mais próxima, com meias unidades positivas arredondadas para cima.
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

Use aritmética decimal. Não arredonde os componentes monetários de entrada e saída separadamente. Por exemplo, uma tarefa Seedance 2.0 de 4 segundos em 480P, sem vídeo de referência, com taxa base 0.07031, multiplicador de canal 1 e multiplicador de conta 1.05, tem uma taxa efetiva de 0.0738255 e um custo líquido de 0.295302 USD (147651 unidades de conta).

O APIMaster mede a duração do vídeo de referência, em vez de confiar em campos do cliente como input_seconds ou reference_seconds. O duration/seconds solicitado controla a duração da saída. Para saídas, a liquidação prefere a duração reportada pelo provedor e sonda a saída quando necessário; medições indisponíveis podem recorrer aos segundos faturáveis do provedor ou à duração solicitada/reservada. O recibo rotula explicitamente a origem. Um fallback nunca é rotulado como uma duração real medida independentemente. Ativos em cache existentes ou rascunhos mais antigos herdados podem não ter detalhes completos de medição por arquivo.

actual_time na resposta do vídeo é o tempo de processamento da tarefa, não a duração do vídeo de saída. usage.completion_tokens, quando presente, é informativo.

Falhas e reembolsos

Falhas de tarefa do provedor e o timeout configurado de 24 horas para tarefas não concluídas acionam um reembolso total automático. Seus recibos permanecem recuperáveis e mostram refunded com valor líquido zero assim que o reembolso é bem-sucedido. Erros temporários de polling/rede não reembolsam nem cancelam imediatamente uma tarefa; o processamento é repetido.

Uma falha de envio confirmada como não cobrada é reembolsada. Um resultado de envio ambíguo é mantido para reconciliação automática (primeira reconciliação assíncrona após aproximadamente 20 minutos; resultados ainda desconhecidos após 24 horas são reembolsados durante a reconciliação). Se o envio não criou uma tarefa pública, não há recibo vinculado à tarefa para essa tentativa. Uma cotação não é uma reserva e não precisa ser liberada.

Não há endpoint público de cancelamento do Seedance. Desconectar ou parar o polling não cancela uma tarefa. As verificações de estado da tarefa impedem que o polling repetido aplique novamente a mesma liquidação/reembolso de conclusão, enquanto o próprio endpoint de recibo é somente leitura. Estas não são uma garantia geral de exatamente uma vez para toda falha de infraestrutura; operações financeiras pendentes não devem ser tratadas como finalizadas.

Idempotência Seedance e recuperação de envios