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}:billingno 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.
- Arredonde a duração medida de cada vídeo de entrada para cima independentemente e depois some:
input_seconds = sum(ceil(each_video_duration)). - Arredonde a duração de saída para o segundo inteiro mais próximo, com meios segundos positivos arredondados para cima.
- Some os segundos faturáveis de entrada e saída.
- Multiplique por
effective_unit_rate, divida poraccount_unit_usde 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.
