APIMaster.ai

Котировки 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 изображения и аудио не облагаются отдельной надбавкой. Количество токенов и стоимость у провайдера не являются входными данными для биллинга.

  1. Округлить измеренную длительность каждого входного видео вверх независимо, затем просуммировать: input_seconds = sum(ceil(each_video_duration)).
  2. Округлить длительность выхода до ближайшей целой секунды, положительные полсекунды округляя вверх.
  3. Сложить биллинговые секунды входа и выхода.
  4. Умножить на 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 нет. Отключение или прекращение опроса не отменяет задачу. Проверки состояния задачи не позволяют повторному опросу повторно применить одно и то же завершение расчёта/возврата, а сам эндпоинт квитанции доступен только для чтения. Это не является универсальной гарантией ровно однократного выполнения для каждой инфраструктурной сбои; ожидающие обработки финансовые операции не должны считаться завершёнными.

Идемпотентность Seedance и восстановление отправок