Presupuestos y recibos de facturación de Seedance
Estima el coste de generación de Seedance y verifica el cargo final mediante recibos persistentes con autenticación.
Presupuestos y recibos de facturación de Seedance
Se aplica a seedance-2.0, seedance-2.5, seedance-2.0-fast y seedance-2.0-mini, en todos los canales de generación. URL base: https://apimaster.ai/v1 (https://apimaster.ai/v1). Autentica todas las solicitudes con Authorization: Bearer YOUR_API_KEY.
Obtener una estimación
POST https://apimaster.ai/v1/videos/quote acepta los mismos parámetros JSON que una solicitud estándar de generación de vídeo, incluidos model, prompt, duration, resolution, video_urls y los demás ajustes compatibles. Actualmente no se admiten presupuestos para borradores, actualizaciones de borradores ni remix.
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}'
La respuesta contiene object: "video.quote", quote_id, expires_at (segundos Unix), binding: false, funds_reserved: false y el objeto billing descrito a continuación. El presupuesto tiene una vigencia orientativa de cinco minutos. No descuenta fondos, no crea tareas ni inicia la generación del proveedor. Por tanto, billing.reserved_amount es "0.000000". El identificador del presupuesto es informativo; no autoriza la generación ni bloquea el precio y no es necesario enviarlo con la solicitud de generación.
El precio se recalcula al enviar la solicitud de generación y queda fijado para esa tarea. La estimación no garantiza un cargo máximo. El coste final puede ser superior o inferior. Las solicitudes de duración automática estiman 30 segundos de salida; requested_output_seconds es -1.
La generación sigue sujeta a la validación del proveedor. Para solicitudes de extensión de vídeo de Seedance 2.5, establece explícitamente aspect_ratio: "adaptive"; los rechazos del proveedor siguen el proceso habitual de reembolso.
Consultar el recibo de la tarea
curl "https://apimaster.ai/v1/videos/task_xxx/billing" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /v1/videos/{task_id}/billing devuelve object: "video.billing_receipt", billing y customer_billing. Usa una clave de API de la cuenta propietaria. Con la clave original, GET /v1/video-submissions/by-key devuelve la facturación del cliente en data.customer_billing. Si final: true, net_amount es el cargo neto definitivo, expresado como cadena decimal en USD. Una tarea antigua con reembolso confirmado puede mostrar un neto definitivo de cero aunque la facturación del proveedor siga sin verificarse. La consulta por ID de tarea devuelve HTTP 404 si la tarea es de otra cuenta o faltan el comprobante y la evidencia de reembolso. Para saber si se puede volver a enviar, consulta los campos de reintento.
El mismo objeto billing aparece en ambas respuestas de consulta:
GET /v1/videos/{task_id}:billingen el nivel superior.GET /v1/video/generations/{task_id}:data.billing.
settlement_status puede ser pending, settled o refunded; los presupuestos usan estimate. La finalización de la generación y la liquidación financiera son estados distintos: los importes solo son definitivos cuando el recibo indica settled o refunded. Consultar repetidamente el recibo no ejecuta generación, liquidación ni reembolsos. Los recibos definitivos conservan su identificador y contenido, también después de un reembolso.
Ejemplos completos de solicitud y respuesta
Ambos ejemplos usan Seedance 2.0 a 480P, una salida solicitada de 4 segundos, una referencia medida de 4.042 segundos, multiplicador de canal 1 y multiplicador de cuenta 1.05. Las duraciones y los importes de la respuesta final proceden de una prueba real; el presupuesto es un ejemplo ilustrativo preparado con las mismas entradas. Los identificadores y las URL son valores de ejemplo. Las tarifas reales son las devueltas por tu API.
1. Obtener un presupuesto
POST https://apimaster.ai/v1/videos/quote, solicitud JSON:
{
"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 | Identificador del modelo; aquí, seedance-2.0. |
prompt |
string | Instrucción para generar el vídeo. |
duration |
integer | Segundos de salida solicitados, no la duración del vídeo de referencia. |
resolution |
string | Resolución de salida; aquí, 480p. |
video_urls |
array |
URL de los vídeos de referencia. Sustituye el ejemplo por un recurso accesible; el servidor mide cada archivo. |
Respuesta del presupuesto:
{
"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
}
}
La entrada de 4.042 segundos se redondea hacia arriba a 5 segundos. Con 4 segundos estimados de salida, se estiman 9 segundos facturables y un coste de 0.408146 USD. El presupuesto no descuenta fondos; los importes finales permanecen en null.
2. Enviar la generación y consultar el resultado
Después de enviar a POST https://apimaster.ai/v1/videos/generations, la respuesta inicial contiene el identificador de la tarea:
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_example"
}
]
}
Consulta después GET https://apimaster.ai/v1/videos/task_example con una clave API de la misma cuenta. Una vez terminadas la generación y la liquidación:
{
"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
}
}
En este caso, el cargo inicial coincide con el coste final, sin cargo adicional ni reembolso. billing.output.actual_seconds es la duración de salida; actual_time es el tiempo de procesamiento. usage.completion_tokens no determina el cargo. Los campos opcionales pueden variar según el canal.
GET https://apimaster.ai/v1/videos/task_example/billing devuelve { "object": "video.billing_receipt", "billing": ... } con el mismo objeto de facturación. La consulta compatible GET https://apimaster.ai/v1/video/generations/task_example lo incluye en data.billing.
Campos externos de la respuesta
| Campo | Tipo | Significado |
|---|---|---|
object |
string | Tipo de respuesta: video.quote, video o video.billing_receipt. |
quote_id |
string | Identificador informativo del presupuesto; no bloquea el precio ni autoriza la generación. |
expires_at |
integer | Caducidad orientativa del presupuesto en segundos Unix, normalmente creación más 300 segundos. |
binding |
boolean | Actualmente false; el presupuesto no garantiza un importe final. |
funds_reserved |
boolean | Actualmente false; el presupuesto no descuenta ni reserva fondos. |
billing |
object | Detalles de facturación explicados individualmente a continuación. |
code |
integer | Código de respuesta del envío; 200 significa enviado, no terminado. |
data |
array | Lista de tareas enviadas; la consulta compatible usa en su lugar un objeto para data. |
data[].status |
string | Estado tras el envío; submitted en este ejemplo. |
data[].task_id |
string | Identificador público de tarea para las consultas posteriores. |
id |
string | Identificador público de tarea en la consulta del resultado. |
task_id |
string | Identificador de tarea, igual a id en este ejemplo. |
model |
string | Nombre público del modelo de generación. |
status |
string | Estado de la tarea; completed indica generación terminada. Comprueba billing.settlement_status para la liquidación definitiva. |
progress |
number | Porcentaje de progreso; 100 al terminar en este ejemplo. |
actual_time |
number | Segundos de procesamiento de la tarea, no duración del vídeo de salida. |
created_at |
integer | Fecha de creación de la tarea en segundos Unix. |
completed_at |
integer | Fecha de finalización de la tarea en segundos Unix. |
metadata |
object | Metadatos del resultado de generación. |
metadata.url |
string | URL de descarga del contenido de vídeo. |
usage |
object | Información de uso del proveedor; puede faltar según el canal. |
usage.completion_tokens |
integer | Tokens declarados por el proveedor; no intervienen en la facturación por segundo de estos cuatro modelos. |
Esquema de facturación
Todos los importes y tarifas unitarias son cadenas decimales. Las duraciones se expresan en segundos. Los campos que admiten valores nulos son JSON null hasta que están disponibles.
| Campo | Tipo | Significado |
|---|---|---|
schema_version |
string | Versión del esquema de facturación; "1" en este ejemplo. |
receipt_id |
string | Identificador estable del recibo; ausente en presupuestos. |
task_id |
string | Identificador público de la tarea vinculada al recibo; ausente en presupuestos. |
settlement_status |
string | estimate, pending, settled, refunded |
model |
string | Identificador público del modelo aplicado. |
resolution |
string | Resolución normalizada usada para facturar. |
tariff_variant |
string | Nivel de tarifa; -input indica referencias de vídeo y esta tarifa se aplica tanto a entrada como a salida. |
tariff_revision |
string | Huella del modelo, nivel de tarifa, precio base configurado y versión de las reglas de facturación. |
currency |
string | Moneda del cargo; actualmente USD. |
unit |
string | Unidad de la tarifa; second significa por segundo. |
base_unit_rate |
decimal string | Precio base configurado por segundo para este modelo y nivel. |
channel_multiplier |
number | Multiplicador agregado de precios del canal aplicado. |
account_multiplier |
number | Multiplicador de cuenta/grupo aplicado; 1.05 en este ejemplo. |
effective_unit_rate |
decimal string | Tarifa por segundo aplicada, fijada al enviar y redondeada a 12 decimales. |
requested_output_seconds |
integer | Duración de salida solicitada; -1 para duración automática. |
estimated_output_seconds |
integer | Segundos de salida estimados; la duración automática se estima en 30 segundos. |
estimated_billable_seconds |
integer | Estimación inicial del total de segundos facturables, incluidas referencias y salida prevista. |
input_videos |
array | Mediciones del servidor por referencia, en el orden de la solicitud. |
input_videos[].index |
integer | Posición de la referencia en la solicitud, empezando por cero. |
input_videos[].media_id |
string | Hash del recurso limitado a la cuenta o identificador de recurso propio; no se devuelve la URL de referencia. |
input_videos[].measured_seconds |
number or null | Duración medida por el servidor antes de redondear; puede ser null para recursos antiguos en caché. |
input_videos[].billable_seconds |
integer | Duración facturable redondeada de esta referencia. |
input_videos[].duration_source |
string | apimaster_probe o apimaster_asset_cache |
billable_input_video_seconds |
integer | Suma de segundos facturables de todas las referencias. |
output |
object or null | Información final de duración de salida, disponible tras liquidar correctamente. |
output.actual_seconds |
number or null | Duración real declarada o medida de salida; null si no está disponible. |
output.billable_seconds |
integer | Segundos de salida usados efectivamente para liquidar. |
output.duration_source |
string | provider_reported, apimaster_probe, provider_billable_seconds, requested_duration_fallback o reservation_fallback |
billable_seconds |
integer or null | Total final de segundos facturables de entrada y salida. |
rounding |
object | Reglas de redondeo de entrada, salida e importes y fórmula de cálculo. |
estimated_amount |
decimal string | Coste inicial estimado; no es un importe final ni garantiza un cargo máximo. |
reserved_amount |
decimal string | Cargo inicial en la cuenta al enviar; cero para presupuestos. No es una retención de autorización bancaria. |
additional_debit_amount |
decimal string | Cargo adicional cuando el coste final supera el cargo inicial. |
final_debit_amount |
decimal string or null | Coste neto final de la tarea tras los ajustes; cero después de un reembolso completo. |
net_amount |
decimal string or null | Coste neto final de la tarea tras los ajustes; cero después de un reembolso completo. |
refunded_amount |
decimal string | Importe devuelto del cargo inicial; coincide con este en un reembolso completo. |
initial_quota_units |
integer | Unidades exactas de cuenta descontadas inicialmente; cero para presupuestos. |
final_quota_units |
integer or null | Unidades exactas del coste neto final; null mientras está pendiente y cero después de un reembolso completo. |
account_unit_usd |
decimal string | "0.000002" por unidad de cuenta. |
media_charges |
object | image, audio y other_reference son cero con la tarifa actual; input_video_unrounded y output_video_unrounded separan los componentes de vídeo antes del redondeo monetario final. |
final_debit_may_exceed_estimate |
boolean | true; la estimación no es un límite rígido de gasto. |
created_at |
integer | Fecha de creación de los detalles de facturación en segundos Unix. |
settled_at |
integer or null | Fecha de liquidación final o reembolso en segundos Unix; null hasta finalizar. |
| Campo | Tipo | Significado |
|---|---|---|
rounding.input_video |
string | ceil_each_file_then_sum: redondea cada entrada hacia arriba y después suma. |
rounding.output_video |
string | nearest_integer_half_up: segundo de salida más cercano; las mitades se redondean hacia arriba. |
rounding.effective_unit_rate |
string | nearest_decimal_12_places_half_up: redondea la tarifa efectiva a 12 decimales. |
rounding.money |
string | nearest_account_unit_half_up: redondea el importe combinado a unidades de cuenta. |
rounding.amount_formula |
string | Fórmula del importe combinado final; entrada y salida no se redondean por separado. |
media_charges.input_video_unrounded |
decimal string | Componente de vídeo de entrada antes del redondeo monetario. |
media_charges.output_video_unrounded |
decimal string | Componente de vídeo de salida antes del redondeo monetario. |
media_charges.image |
decimal string | Recargo independiente por imágenes; actualmente cero. |
media_charges.audio |
decimal string | Recargo independiente por audio; actualmente cero. |
media_charges.other_reference |
decimal string | Recargo por otras referencias; actualmente cero. |
Recalcular el coste final
Cuando hay vídeo de referencia, la tarifa de entrada de vídeo se aplica tanto a la salida como a los segundos de referencia. Las imágenes y el audio no tienen recargos independientes con la tarifa actual de Seedance. Los tokens y el coste del proveedor no intervienen en la facturación.
- Redondea hacia arriba la duración medida de cada vídeo de entrada por separado y suma:
input_seconds = sum(ceil(each_video_duration)). - Redondea la duración de salida al segundo entero más cercano; las mitades positivas se redondean hacia arriba.
- Suma los segundos facturables de entrada y salida.
- Multiplica por
effective_unit_rate, divide poraccount_unit_usdy redondea el total una sola vez a unidades enteras de cuenta; las mitades positivas se redondean hacia arriba.
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
Usa aritmética decimal. No redondees por separado los componentes monetarios de entrada y salida. Por ejemplo, una tarea de Seedance 2.0 de 4 segundos a 480P, sin vídeo de referencia, con tarifa base 0.07031, multiplicador de canal 1 y multiplicador de cuenta 1.05, tiene una tarifa efectiva de 0.0738255 y un coste neto de 0.295302 USD (147651 unidades de cuenta).
APIMaster mide la duración del vídeo de referencia y no confía en campos del cliente como input_seconds o reference_seconds. duration/seconds indica la duración solicitada de salida. Para la salida, la liquidación prioriza la duración declarada por el proveedor y mide el archivo cuando es necesario; si no hay medición disponible, puede usar los segundos facturables del proveedor o la duración solicitada/preestimada. El recibo identifica la fuente. Un valor alternativo nunca se presenta como duración real medida de forma independiente. Los recursos antiguos en caché o los borradores heredados pueden carecer de detalles completos por archivo.
actual_time en la respuesta de vídeo es el tiempo de procesamiento de la tarea, no la duración del vídeo. usage.completion_tokens, cuando aparece, es informativo.
Fallos y reembolsos
Los fallos de tareas del proveedor y el tiempo límite configurado de 24 horas para tareas sin terminar activan un reembolso completo automático. Los recibos siguen disponibles y muestran refunded con importe neto cero una vez realizado el reembolso. Los errores temporales de consulta o red no reembolsan ni cancelan inmediatamente la tarea; se reintenta el procesamiento.
Un fallo de envío confirmado como no cobrado se reembolsa. Si el resultado del envío es incierto, se retiene para conciliación automática (primera conciliación asíncrona aproximadamente a los 20 minutos; los resultados que siguen siendo desconocidos tras 24 horas se reembolsan durante la conciliación). Si el envío no creó una tarea pública, ese intento no tiene recibo asociado a una tarea. El presupuesto no reserva fondos y no requiere liberación.
Actualmente no existe un endpoint público de cancelación de Seedance. Desconectarse o dejar de consultar no cancela una tarea. Las comprobaciones de estado evitan volver a aplicar la liquidación o el reembolso de una misma tarea terminada; el endpoint de recibos es de solo lectura. Esto no garantiza una ejecución exactamente una vez ante cualquier fallo de infraestructura; las operaciones financieras pendientes no deben considerarse definitivas.
