Котировки Seedance и платежные квитанции
Оценка стоимости генерации в Seedance и проверка фактического списания с помощью аутентифицированных долгосрочных платёжных квитанций.
Котировки Seedance и платежные квитанции
Применяется к seedance-2.0, seedance-2.5, seedance-2.0-fast и seedance-2.0-mini на всех каналах генерации. Базовый URL: https://apimaster.ai/v1 (https://apimaster.ai/v1). Аутентифицируйте все запросы с помощью Authorization: Bearer YOUR_API_KEY.
Получение оценки
POST https://apimaster.ai/v1/videos/quote принимает те же параметры JSON, что и стандартный запрос на генерацию видео, включая model, prompt, duration, resolution, video_urls и другие поддерживаемые настройки генерации. Котировки для черновой генерации, обновления черновиков и ремикса в настоящее время не поддерживаются.
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}'
Ответ содержит object: "video.quote", quote_id, expires_at (Unix-секунды), binding: false, funds_reserved: false и объект billing, описанный ниже. Котировка имеет рекомендательный срок действия пять минут. Она не списывает средства, не создаёт задачу и не запускает генерацию у провайдера. Поэтому billing.reserved_amount равен "0.000000". Идентификатор котировки носит информационный характер; это не токен авторизации или фиксации цены, и его не нужно передавать при генерации.
Цена пересчитывается при фактической отправке и фиксируется для этой задачи. Оценка не является гарантией максимального списания. Фактическая стоимость завершённой задачи может оказаться выше или ниже оценки. Для запросов с автоматической длительностью используется оценка выходного видео в 30 секунд; requested_output_seconds равен -1.
Генерация по-прежнему подлежит валидации со стороны провайдера. Для запросов на расширение видео Seedance 2.5 явно устанавливайте aspect_ratio: "adaptive"; отклонение провайдера обрабатывается через обычный цикл возврата средств.
Получение квитанции по задаче
curl "https://apimaster.ai/v1/videos/task_xxx/billing" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /v1/videos/{task_id}/billing возвращает object: "video.billing_receipt", billing и customer_billing. Используйте API-ключ аккаунта владельца задания. С исходным ключом GET /v1/video-submissions/by-key показывает расчёт с клиентом в data.customer_billing. При final: true значение net_amount окончательное и представлено десятичной строкой в USD. Для старого задания с подтверждённым возвратом сумма может быть равна нулю, даже если расходы поставщика ещё не подтверждены. Запрос по идентификатору возвращает HTTP 404 для чужого задания или при отсутствии квитанции и подтверждения возврата. Возможность повторной отправки определяют поля разрешения повтора.
Тот же объект billing включается в оба ответа при запросе задачи:
GET /v1/videos/{task_id}:billingверхнего уровня.GET /v1/video/generations/{task_id}:data.billing.
settlement_status принимает значения pending, settled или refunded; в ответах котировки используется estimate. Завершение задачи и финансовое завершение — разные события: считайте суммы окончательными только тогда, когда статус квитанции — settled или refunded. Повторные запросы квитанции не запускают ни генерацию, ни расчёт, ни возврат средств. Окончательные квитанции сохраняют один и тот же идентификатор и содержимое, в том числе после возврата средств.
Полные примеры запросов и ответов
Оба примера используют Seedance 2.0 с разрешением 480P, запрошенный выход длиной 4 секунды, один эталонный файл с измеренной длительностью 4,042 секунды, множитель канала 1 и множитель аккаунта 1,05. Длительности завершения и суммы получены в ходе живого теста; котировка — иллюстративный пример, собранный для соответствующих входных данных. Идентификаторы и URL медиафайлов являются заполнителями. Фактические тарифы берутся из вашего ответа API.
1. Получение котировки
POST https://apimaster.ai/v1/videos/quote, 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"
]
}
| Поле | Тип | Значение |
|---|---|---|
model |
string | Идентификатор модели, здесь seedance-2.0. |
prompt |
string | Промпт генерации. |
duration |
integer | Запрошенные секунды выходного видео, а не длительность эталонного видео. |
resolution |
string | Разрешение выходного видео, здесь 480p. |
video_urls |
array |
URL эталонных видео. Замените заполнитель на доступные медиафайлы; сервер измеряет каждый файл. |
Ответ котировки:
{
"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
}
}
Вход длиной 4,042 секунды округляется вверх до 5 секунд. С 4 оценочными секундами выхода оценка покрывает 9 секунд и составляет 0.408146 USD. Котировка не списывает средства; итоговые суммы остаются null.
2. Отправка генерации и запрос завершения
После отправки в POST https://apimaster.ai/v1/videos/generations начальный ответ содержит идентификатор задачи:
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_example"
}
]
}
Затем выполните GET https://apimaster.ai/v1/videos/task_example, используя API-ключ из того же аккаунта. После завершения генерации и расчёта:
{
"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
}
}
В данном случае начальное списание равно итоговой стоимости, без дополнительного списания или возврата. billing.output.actual_seconds — это длительность выходного видео; actual_time — время обработки. usage.completion_tokens не определяет сумму к оплате. Необязательные поля могут различаться в зависимости от канала.
GET https://apimaster.ai/v1/videos/task_example/billing возвращает { "object": "video.billing_receipt", "billing": ... } с тем же объектом биллинга. Совместимый запрос GET https://apimaster.ai/v1/video/generations/task_example размещает его в data.billing.
Поля внешнего ответа
| Поле | Тип | Значение |
|---|---|---|
object |
string | Тип ответа: video.quote, video или video.billing_receipt. |
quote_id |
string | Информационный идентификатор котировки; не является фиксацией цены или авторизацией генерации. |
expires_at |
integer | Рекомендательный срок действия котировки в Unix-секундах, обычно момент создания плюс 300 секунд. |
binding |
boolean | В настоящее время false; котировка не гарантирует итоговую сумму. |
funds_reserved |
boolean | В настоящее время false; котировка не списывает и не резервирует средства. |
billing |
object | Платёжные сведения, отдельно описанные ниже. |
code |
integer | Код ответа на отправку; 200 означает отправлено, а не завершено. |
data |
array | Список отправленных задач; совместимый запрос вместо этого использует объект для data. |
data[].status |
string | Статус отправки, в этом примере submitted. |
data[].task_id |
string | Публичный идентификатор задачи, используемый для последующих запросов. |
id |
string | Публичный идентификатор задачи в запросе завершения. |
task_id |
string | Идентификатор задачи, равен id в этом примере. |
model |
string | Публичное имя модели генерации. |
status |
string | Статус задачи; completed означает завершение генерации. Проверьте billing.settlement_status для итогового расчёта. |
progress |
number | Процент выполнения; в этом примере 100 при завершении. |
actual_time |
number | Секунды обработки задачи, а не длительность выходного видео. |
created_at |
integer | Временная метка создания задачи в Unix-секундах. |
completed_at |
integer | Временная метка завершения задачи в Unix-секундах. |
metadata |
object | Метаданные результата генерации. |
metadata.url |
string | URL для скачивания содержимого видео. |
usage |
object | Информация об использовании от провайдера; может отсутствовать в зависимости от канала. |
usage.completion_tokens |
integer | Количество токенов провайдера; не используется для посекундного биллинга этих четырёх моделей. |
Схема биллинга
Все денежные суммы и ставки являются десятичными строками. Длительности — в секундах. Обязательные поля имеют тип JSON null, пока данных нет.
| Поле | Тип | Значение |
|---|---|---|
schema_version |
string | Версия схемы биллинга, в этом примере "1". |
receipt_id |
string | Стабильный идентификатор квитанции; отсутствует в котировках. |
task_id |
string | Публичный идентификатор задачи, связанный с квитанцией; отсутствует в котировках. |
settlement_status |
string | estimate, pending, settled, refunded |
model |
string | Применённый публичный идентификатор модели. |
resolution |
string | Нормализованное разрешение, используемое для биллинга. |
tariff_variant |
string | Уровень тарифа; -input означает видеоэталоны, при этом эта ставка применяется и к входу, и к выходу. |
tariff_revision |
string | Отпечаток модели, уровня тарифа, настроенной базовой ставки и версии правил биллинга |
currency |
string | Валюта списания, в настоящее время USD. |
unit |
string | Единица ставки; second означает «в секунду». |
base_unit_rate |
decimal string | Настроенная базовая цена за секунду для этой модели и уровня. |
channel_multiplier |
number | Применённый совокупный множитель ценообразования канала. |
account_multiplier |
number | Применённый множитель аккаунта/группы, в этом примере 1,05. |
effective_unit_rate |
decimal string | Применённая посекундная ставка, зафиксированная при отправке и округлённая до 12 знаков после запятой. |
requested_output_seconds |
integer | Запрошенная длительность выхода; -1 для автоматической длительности |
estimated_output_seconds |
integer | Оценочные секунды выхода; для автоматической длительности оценка составляет 30 секунд. |
estimated_billable_seconds |
integer | Начальная оценка общего числа биллинговых секунд, включая эталонные видео и ожидаемый выход. |
input_videos |
array | Измерения сервера для каждого эталона, в порядке запроса |
input_videos[].index |
integer | Позиция эталонного видео в запросе, отсчёт с нуля. |
input_videos[].media_id |
string | Хеш медиафайла в пределах аккаунта или идентификатор принадлежащего ресурса; URL эталонного видео не возвращается. |
input_videos[].measured_seconds |
number or null | Измеренная сервером длительность до округления; может быть null для старых кэшированных ресурсов |
input_videos[].billable_seconds |
integer | Округлённая биллинговая длительность этого эталона |
input_videos[].duration_source |
string | apimaster_probe или apimaster_asset_cache |
billable_input_video_seconds |
integer | Сумма биллинговых секунд по каждому эталону |
output |
object or null | Информация о фактической длительности выхода, доступна после успешного расчёта |
output.actual_seconds |
number or null | Фактическая заявленная/измеренная длительность выхода; null, если недоступна |
output.billable_seconds |
integer | Секунды выхода, фактически использованные при расчёте |
output.duration_source |
string | provider_reported, apimaster_probe, provider_billable_seconds, requested_duration_fallback или reservation_fallback |
billable_seconds |
integer or null | Итоговые совокупные биллинговые секунды входа/выхода |
rounding |
object | Правила округления входа, выхода и денежных сумм, а также формула суммы |
estimated_amount |
decimal string | Начальная оценка стоимости; не итоговая сумма и не гарантия максимального списания. |
reserved_amount |
decimal string | Начальное списание с аккаунта при отправке; для котировок равно нулю; не является банковской авторизационной блокировкой. |
additional_debit_amount |
decimal string | Дополнительное списание, когда итоговая стоимость превышает начальное списание. |
final_debit_amount |
decimal string or null | Итоговая чистая стоимость задачи после корректировок; ноль после полного возврата |
net_amount |
decimal string or null | Итоговая чистая стоимость задачи после корректировок; ноль после полного возврата |
refunded_amount |
decimal string | Сумма, возвращённая из начального списания; равна начальному списанию при полном возврате. |
initial_quota_units |
integer | Точные единицы аккаунта, списанные изначально; для котировок равно нулю. |
final_quota_units |
integer or null | Точные единицы аккаунта итоговой чистой стоимости; null, пока расчёт не завершён; ноль после полного возврата. |
account_unit_usd |
decimal string | "0.000002" за единицу аккаунта |
media_charges |
object | image, audio, other_reference равны нулю по текущему тарифу; input_video_unrounded и output_video_unrounded разделяют видео-компоненты до окончательного денежного округления |
final_debit_may_exceed_estimate |
boolean | true; оценка не является жёстким лимитом расходов |
created_at |
integer | Временная метка создания платёжных сведений в Unix-секундах. |
settled_at |
integer or null | Временная метка окончательного расчёта или возврата в Unix-секундах; null, пока не завершено. |
| Поле | Тип | Значение |
|---|---|---|
rounding.input_video |
string | ceil_each_file_then_sum: округлить каждый входной файл вверх, затем просуммировать. |
rounding.output_video |
string | nearest_integer_half_up: ближайшая секунда выхода, полсекунды округляются вверх. |
rounding.effective_unit_rate |
string | nearest_decimal_12_places_half_up: округлить эффективную ставку до 12 знаков после запятой. |
rounding.money |
string | nearest_account_unit_half_up: округлить совокупную сумму до единиц аккаунта. |
rounding.amount_formula |
string | Формула итоговой совокупной суммы; суммы входа и выхода не округляются отдельно. |
media_charges.input_video_unrounded |
decimal string | Компонент входного видео до денежного округления. |
media_charges.output_video_unrounded |
decimal string | Компонент выходного видео до денежного округления. |
media_charges.image |
decimal string | Отдельная надбавка за изображения, в настоящее время ноль. |
media_charges.audio |
decimal string | Отдельная надбавка за аудио, в настоящее время ноль. |
media_charges.other_reference |
decimal string | Надбавка за другие эталоны, в настоящее время ноль. |
Пересчёт итоговой стоимости
При наличии эталонного видео уровень «видео на входе» применяется как к секундам выхода, так и к секундам эталонного видео. По текущему тарифу Seedance изображения и аудио не облагаются отдельной надбавкой. Количество токенов и стоимость у провайдера не являются входными данными для биллинга.
- Округлить измеренную длительность каждого входного видео вверх независимо, затем просуммировать:
input_seconds = sum(ceil(each_video_duration)). - Округлить длительность выхода до ближайшей целой секунды, положительные полсекунды округляя вверх.
- Сложить биллинговые секунды входа и выхода.
- Умножить на
effective_unit_rate, разделить наaccount_unit_usd, затем один раз округлить общую сумму до ближайшей целой единицы аккаунта, положительные половины единиц округляя вверх.
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
Используйте десятичную арифметику. Не округляйте денежные компоненты входа и выхода отдельно. Например, задача Seedance 2.0 длительностью 4 секунды при 480P без эталонного видео, с базовой ставкой 0.07031, множителем канала 1 и множителем аккаунта 1.05, имеет эффективную ставку 0.0738255 и чистую стоимость 0.295302 USD (147651 единиц аккаунта).
APIMaster измеряет длительность эталонного видео, не доверяя клиентским полям, таким как input_seconds или reference_seconds. Запрошенные duration/seconds управляют длительностью выхода. Для выходов при расчёте предпочтение отдаётся длительности, заявленной провайдером, а при необходимости выполняется зондирование выхода; недоступные измерения могут быть заменены биллинговыми секундами провайдера или запрошенной/зарезервированной длительностью. Квитанция явно указывает источник. Резервный вариант никогда не обозначается как независимо измеренная фактическая длительность. У существующих кэшированных ресурсов или унаследованных старых черновиков могут отсутствовать полные данные измерений по каждому файлу.
actual_time в ответе видео — это время обработки задачи, а не длительность выходного видео. usage.completion_tokens, если присутствует, носит информационный характер.
Сбои и возвраты средств
Сбои задач у провайдера и настроенный 24-часовой таймаут незавершённых задач приводят к автоматическому полному возврату средств. Их квитанции остаются доступными для получения и после успешного возврата показывают refunded с нулевой чистой суммой. Временные ошибки опроса/сети не приводят к немедленному возврату или отмене задачи; обработка повторяется.
Неудачная отправка, подтверждённая как неоплаченная, возвращается. Неоднозначный результат отправки передаётся на автоматическую сверку (первый асинхронный разбор примерно через 20 минут; всё ещё неизвестные результаты возвращаются при сверке через 24 часа). Если отправка не создала публичную задачу, квитанции, привязанной к задаче, для этой попытки нет. Котировка не является бронированием и не требует освобождения.
Публичной конечной точки отмены Seedance нет. Отключение или прекращение опроса не отменяет задачу. Проверки состояния задачи не позволяют повторному опросу повторно применить одно и то же завершение расчёта/возврата, а сам эндпоинт квитанции доступен только для чтения. Это не является универсальной гарантией ровно однократного выполнения для каждой инфраструктурной сбои; ожидающие обработки финансовые операции не должны считаться завершёнными.
