Ръководство за API на Seedance 2.5 Flash: асинхронни задачи, ограничения, грешки

AIHubMix8 мин четене
Ръководство за API на Seedance 2.5 Flash: асинхронни задачи, ограничения, грешки

Използвайте doubao-seedance-2-5-flash с POST /ai/v1/videos, проверявайте състоянието на задачата и след това изтеглете резултата. Текущата схема на AIHubMix поддържа изход с резолюция 480p/720p, клипове с дължина 4–30 секунди и до 10 изображения, 5 видеоклипа и 5 аудиофайла като референции. Клиентите от по-стари версии, които използват /v1/videos, трябва да променят както крайната точка, така и ID на модела.

Това ръководство беше проверено на 16 ноември 2026 г. Както краткият ID по-горе, така и doubao-seedance-2-5-flash-261115 върнаха схема на модела и отхвърлиха заявка за 1080p с 400 schema_violation. Отделен опит за създаване на 4-секунден видеоклип с резолюция 480p върна 402 insufficient_quota; видео не беше генерирано. Работният процес по-долу следва текущата схема и документацията, но при тази проверка не бяха потвърдени от край до край успешно генериране, латентност, MOV изход или редактиране.

Предварителни изисквания и откриване на схемата

Страницата на модела Seedance 2.5 Flash посочва модела под краткия ID, използван в цялото това ръководство. Преди да изпратите задача:

  1. Активирайте асинхронните медийни задачи в конзолата на AIHubMix. Документираната грешка за акаунт без активирана тази функция е 403 async_not_enabled.
  2. Уверете се, че API ключът има достъп и че акаунтът разполага с достатъчен баланс. При проверката на живо беше върнато 402 insufficient_quota със съобщението Your account has insufficient quota. Add credits and try again.
  3. Задайте AIHUBMIX_API_KEY във вашата обвивка. Не включвайте ключа в изходните файлове или кода на браузъра.
  4. Извлечете текущата схема; заявката за откриването ѝ не изисква удостоверяване.
curl --fail-with-body -sS \
  'https://aihubmix.com/call/schema/models/doubao-seedance-2-5-flash/endpoints' \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'

Схемата от 16 ноември посочва само /ai/v1/videos за Flash. Тя приема стойности resolution 480p и 720p (по подразбиране 720p), цяло число от 4 до 30 за duration или -1 за продължителност, избрана от модела. Задайте изрично продължителността, ако искате предвидим бюджет.

Създаване, проверка на състоянието и изтегляне

API за генериране на видео на AIHubMix разделя създаването, заявките за състояние и изтеглянията. Успешният HTTP отговор при създаването означава, че задачата е приета; само status: "completed" потвърждава завършването ѝ. Заявката за състоянието може да върне HTTP 200, дори когато задачата има status: "failed".

Изпратете задача за преобразуване на текст във видео

Този пример заявява 10-секунден продуктов клип с резолюция 720p, формат 16:9 и аудио. Използва се само текст, така че не се разчита на референтни изображения, хоствани другаде.

curl --fail-with-body -sS -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2-5-flash",
    "prompt": "A matte ceramic espresso cup sits on wet slate as warm morning light sweeps across rising steam. The camera slowly dollies in. Quiet cafe ambience.",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": true
  }'

Запазете незабавно върнатия id на задачата. Изпращайте заявка GET /ai/v1/videos/{id} на всеки 15 секунди, докато състоянието стане completed, failed или cancelled. За активно проследяване използвайте крайната точка за подробностите на видеото: тя актуализира състоянието от доставчика, докато общият списък със задачи не може да замести тази проверка. След завършване изтеглете видеото чрез GET /ai/v1/videos/{id}/content, като използвате същата Bearer заглавка.

Пълен Python клиент

Инсталирайте зависимостта с python3 -m pip install requests, запазете следния код във файл seedance_flash.py, след което изпълнете python3 seedance_flash.py в обвивката, в която е зададен API ключът ви. Този пример реализира документирания процес; грешката за недостатъчен баланс по-горе попречи на цялостно тестване на генерирането.

import os
import time
from pathlib import Path

import requests

BASE_URL = "https://aihubmix.com"
HEADERS = {
    "Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}",
    "Content-Type": "application/json",
}
PAYLOAD = {
    "model": "doubao-seedance-2-5-flash",
    "prompt": "A matte ceramic espresso cup sits on wet slate as warm morning light sweeps across rising steam. The camera slowly dollies in. Quiet cafe ambience.",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": True,
}

# Submit once. A network timeout does not prove that creation failed.
response = requests.post(
    f"{BASE_URL}/ai/v1/videos", headers=HEADERS, json=PAYLOAD, timeout=60
)
response.raise_for_status()
task = response.json()
task_id = task["id"]
print(f"Task ID: {task_id}", flush=True)

deadline = time.monotonic() + 20 * 60
while task["status"] not in {"completed", "failed", "cancelled"}:
    if time.monotonic() >= deadline:
        raise TimeoutError(f"Still waiting for {task_id}; query it again, do not recreate it.")
    time.sleep(15)
    response = requests.get(
        f"{BASE_URL}/ai/v1/videos/{task_id}", headers=HEADERS, timeout=30
    )
    response.raise_for_status()
    task = response.json()

if task["status"] != "completed":
    raise RuntimeError(f"Task {task_id}: {task.get('error') or task['status']}")

response = requests.get(
    f"{BASE_URL}/ai/v1/videos/{task_id}/content", headers=HEADERS, timeout=120
)
response.raise_for_status()
Path("seedance_flash_10s.mp4").write_bytes(response.content)
print("Saved seedance_flash_10s.mp4")

20-минутният срок е ограничение за изчакване от страна на клиента, а не анулиране от сървъра или гаранция за времето за генериране. Ако проверката на състоянието или изтеглянето не успее, запазете ID на задачата и повторете тази операция. Не изпращайте автоматично нова заявка за генериране след изтичане на срока или при неясно състояние от страна на доставчика.

Според официалните цени на BytePlus за онлайн извеждане Flash струва $7.00 за милион токени без видео вход или $4.30 с видео вход при 480p/720p. За примера само с текст изчислената стойност е 10 × 1280 × 720 × 24 / 1024 = 216,000 токена: $1.51 с Flash срещу $2.31 с водещия модел 2.5 при 720p. Това са изчислени оценки по цените на BytePlus, а не измерена сметка от AIHubMix.

Референции и уебкуки

За да насочвате генерирането на клип с медийни файлове, добавете елементи input_references, съдържащи type (image_url, video_url или audio_url) и url, сочещ към медия, до която има достъп. Схемата ограничава тези типове до 10 / 5 / 5. За управление на първия/последния кадър използвайте вместо това frame_images; всеки елемент съдържа frame_type и вложено image_url.url. Не използвайте едновременно непразни frame_images и input_references. Работните процеси с кадри изискват aspect_ratio: "adaptive", а за последен кадър е необходим и първи кадър.

Документацията за асинхронните задачи описва HTTPS обратни извиквания чрез webhook_url. Текущата схема на Flash включва това поле, но пропуска webhook_events_filter и задава additionalProperties: false, затова не включвайте филтъра, когато следвате схемата на този модел. Според документацията по подразбиране се изпращат събитията completed, failed и cancelled. Доставката е поне веднъж, с до шест опита и интервали за повторение от 1, 4, 16, 64 и 256 секунди; премахвайте дубликатите по event_id. Обратните извиквания на ниво задача нямат отделна тайна за подписване, затова направете заявка за задачата, за да потвърдите крайното ѝ състояние. В документацията са описани абонаменти на ниво акаунт за приложения, които се нуждаят от проверка на подписа.

Грешки: какво беше измерено и какво е описано в документацията

1080p: измерено отхвърляне от схемата

И двата ID на моделите в AIHubMix върнаха HTTP 400 за заявка с продължителност 4 секунди и resolution: "1080p". Върнатите полета за грешка бяха:

{
  "error": {
    "code": "schema_violation",
    "message": "`resolution` must be one of: 480p, 720p, null.",
    "type": "invalid_request_error"
  }
}

Отговорът съдържаше и ID за проследяване на заявката, което е пропуснато тук. Това е наблюдавано отхвърляне от шлюза, а не изведена по предположение грешка от upstream. То не доказва нито успешно генериране, нито измерена скорост.

Другите ограничения по-долу са взети от текущата схема на Flash; тези невалидни комбинации не бяха изпращани отделно при проверката на живо.

Проблем с входните данни Изискване на схемата Корекция
Изход 4K 480p или 720p Намалете резолюцията
Прекалено много референции 10 изображения / 5 видеоклипа / 5 аудиофайла Намалете броя
Два масива с референции Един непразен масив Изберете работен процес
Само последен кадър Необходим е и първи кадър Посочете и двата кадъра
Фиксирано съотношение на страните с кадри Адаптивно съотношение на страните Използвайте адаптивно

Референции с реални хора: използвайте потвърдени ресурси

AIHubMix описва doubao_real_person_required като грешката, която се връща, когато Doubao отхвърли изображение на реален човек по конкретни причини, свързани с поверителността. Тази грешка не беше задействана при проверката. Документираното съобщение е:

Тази заявка използва изображение на реален човек. Завършете потвърждаването на реалния човек и използвайте активна референция към ресурс. Вижте https://docs.aihubmix.com/cn/api/doubao-real-person-assets.

Следвайте Ръководството за ресурси с реални хора на Doubao: създайте група чрез /ai/v1/asset-groups, създайте сесия за потвърждение чрез /ai/v1/asset-groups/{id}/verification-sessions, накарайте изобразения човек да завърши уеб потвърждението, регистрирайте ресурса чрез /ai/v1/asset-groups/{id}/assets и изчакайте той да стане активен. Използвайте asset://<ASSET_ID> в референцията за генериране. Обикновен URL към снимка не замества процеса на получаване на съгласие и регистриране на ресурс.

Квота, размер на заявката и изтегляния

Измерената грешка 402 insufficient_quota попречи заявката с валидна резолюция да стигне до генериране. Заредете баланса, преди да опитате отново; промяната на правилен промпт или ID на модел няма да отстрани този отговор. 403 async_not_enabled е различна, документирана грешка за предварително изискване, която изисква активиране в конзолата.

AIHubMix документира ограничение от 32 MiB за тялото на заявката и 413 request_too_large. Публичните URL адреси предотвратяват раздуването на тялото на заявката заради Base64, но реферираните медийни файлове все пак трябва да спазват собствените ограничения на модела за размер и формат.

Запазвайте генерираното видео възможно най-скоро. Съществуващото ръководство на AIHubMix за интеграцията със Seedance 2.5 предупреждава, че URL адресите към изходните файлове са краткотрайни — приблизително 30 минути; тук не беше потвърден фиксиран период на съхранение за Flash. Видео API може да върне expires_at: null, което не обещава безсрочно съхранение. Документираните грешки при изтегляне включват 410 artifact_expired и 429 too_many_downloads. Ако изтеглянето върне временна грешка на услугата, опитайте да изтеглите отново чрез съществуващата задача, вместо да генерирате клипа пак.

Капани при миграция, които могат да засегнат и валидна заявка

Ръководството на Volcengine за Seedance 2.5 изрично включва Flash в това семейство и потвърждава изход във формат MOV, редактиране и удължаване, но тези възможности на доставчика трябва да се разграничават от потвърденото чрез шлюза.

  • Полета за MOV и редактиране са налични, но тук не бяха тествани от край до край. Схемата на Flash приема extra.output_format: "mp4" или "mov" и стойности auto, reference, edit и extend за extra.omni_reference_task_type. Ако изпратите изрично поле за типа задача, схемата изисква непразно input_references. Типът edit изисква допълнително видео референция, адаптивно съотношение на страните и duration: -1; типът extend изисква видео референция и адаптивно съотношение на страните.
  • Изрично зададеният тип задача не гарантира, че моделът ще го приеме. Ark документира асинхронна грешка InvalidParameter.TaskTypeConstraint, когато предполагаемият тип задача е в конфликт с параметрите, и InvalidParameter.TaskTypeMismatch, когато предполагаемият тип се различава от зададения изрично. Точното съответствие в AIHubMix не беше измерено; проверете върнатото error на задачата, вместо да приемате, че има един-единствен код на шлюза.
  • Flash не поддържа преминаване от Draft към финален резултат. Доставчикът ограничава двуетапния работен процес от 480p Draft до финален резултат до водещия модел 2.5. Flash не го поддържа, а в текущите схеми на AIHubMix и за двата модела липсват draft и draft_task.
  • Видео входът променя таксуването. Официалното таксуване отчита продължителността както на входното, така и на изходното видео и може да налага минимален праг за токените. Цената от $4.30/M не гарантира, че задача с видео насоки ще струва по-малко от иначе идентична задача само с текст. Проверявайте действителното използване и таксуването по акаунта, вместо да разчитате само на формулата.
  • Някои описания остават неясни. Схемата на Flash за gateway излага extra.priority, extra.safety_identifier и extra.tools, но описанията им все още гласят „само за серия 2.0“. Справочникът на Ark за създаване на задачи включва priority и tools и за семейството 2.5. Самото наличие в схемата не потвърждава ефекта им в AIHubMix; проверете конкретната функционалност, преди да разчитате на нея в продукционна среда.

Контролен списък преди стартиране

  • Активирайте асинхронните задачи и проверете наличния кредит по сметката.
  • Използвайте краткия идентификатор на Flash с /ai/v1/videos и извлечете актуалната му схема.
  • Изберете 480p или 720p и задайте изрично продължителност между 4 и 30 секунди.
  • Ограничете референциите до 10 изображения, 5 видеоклипа и 5 аудиоклипа.
  • Дръжте референциите към кадри отделно и използвайте адаптивно съотношение на страните за тях.
  • Използвайте проверени активни активи за референции, наподобяващи реални хора.
  • Запазете идентификатора на задачата, проверете крайния ѝ статус и изтеглете резултата своевременно.
  • При неясно състояние на генерирането опитайте отново да проверите статуса или да изтеглите резултата от съществуващата задача.

Често задавани въпроси

Мога ли да използвам съвместимия с OpenAI път /v1/videos за Flash?
В актуалната схема на Flash е посочен само /ai/v1/videos. Използвайте този нативен асинхронен път в примерите от това ръководство.

Защо заявка с изображение на кадър се проваля при aspect_ratio: "16:9"?
Схемата на Flash изисква aspect_ratio: "adaptive", когато са подадени непразни frame_images. За последен кадър е необходим и първи кадър, а референциите към кадри не могат да се комбинират с непразно input_references.

Как да отстраня грешката doubao_real_person_required?
Следвайте процедурата за лична проверка и регистрация на актив, изчакайте активът да стане активен и го посочете чрез URI на актива. Кодът обозначава конкретен отказ поради поверителност от Doubao; при тази проверка той не беше възпроизведен.

Защо кратко референтно видео може да струва повече от предвиденото по формулата?
Правилата на доставчика за таксуване може да налагат минимален праг за токените, когато входът включва видео. Формулата е приблизителна оценка; проверете действителното потребление и записите за таксуване по сметката, за да установите начислената сума.

Плаща ли се за неуспешни генерирания или откази от модерацията?
Официалните правила за таксуване на BytePlus и Volcengine начисляват такса за успешни генерирания и посочват, че неуспешните генерирания и отказите при модерация на съдържание не се таксуват. Документацията на AIHubMix за грешки препоръчва да се проверят записите за таксуване за исторически начисления; тук не беше измерено таксуване за успешно или неуспешно генериране.

Колко време имам, за да изтегля резултат от Flash?
Изтеглете го веднага след завършване. В съществуващото ръководство за Seedance 2.5 се посочва, че URL адресите са валидни приблизително 30 минути, но точният срок на съхранение за Flash не беше проверен, а поле за изтичане със стойност null не означава, че резултатът е постоянен.

Поддържат ли се MOV изход и редактиране/удължаване чрез AIHubMix?
В актуалната схема на Flash съответните полета са налични в extra, а доставчикът документира тези възможности. Работата им от край до край чрез AIHubMix не беше проверена, тъй като тестът за създаване приключи с отговор за недостатъчна квота.

Продължете с поредицата за Seedance 2.5 Flash

Източници

Документацията и схемата бяха проверени на 16 ноември 2026 г.; отговорите при валидирането бяха записани в 08:26 UTC. Цените са официални оценки на BytePlus, а не измерени такси на gateway.

Един шлюз към множество AI доставчици. Създаден за продукционна среда.

Посетете AIHubMix