APIMaster.ai

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}: billing en 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.

  1. Redondea hacia arriba la duración medida de cada vídeo de entrada por separado y suma: input_seconds = sum(ceil(each_video_duration)).
  2. Redondea la duración de salida al segundo entero más cercano; las mitades positivas se redondean hacia arriba.
  3. Suma los segundos facturables de entrada y salida.
  4. Multiplica por effective_unit_rate, divide por account_unit_usd y 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.

Idempotencia de Seedance y recuperación de envíos