Справочник · версия 2026-11-01

API

Базовый адрес https://api.hawklance.ai/v1. Ключ передаётся в заголовке Authorization: Bearer …, подробнее в разделе «Ключи и доступ».

Скачать описание OpenAPI 3.1

Предварительная версия: рендер пока эмулируется, поле simulated в ответе это показывает.

Видео

Создание ролика, статус, отмена и удаление. Генерация идёт асинхронно: создайте видео и следите за статусом запросами или вебхуком.

Создать видео

post/v1/videos

Ставит ролик в очередь и сразу отвечает. Передайте prompt либо template. Боевой ключ сразу списывает токены; при ошибке рендера или отмене они возвращаются.

Параметры

Idempotency-Keystring
Повтор с тем же ключом вернёт уже созданное видео, а не новое. Пригодится при обрыве сети.
до 200 символов

Тело запроса

promptstring
Описание ролика. Обязательно, если нет template.
до 12 000 символов
templatestring
Идентификатор шаблона. Обязателен, если нет prompt.
inputsobject
Значения полей шаблона: id файлов или текст. Поля — в GET /templates/{id}.
imagesstring[]
Id фото для своего описания, по порядку <Picture 1>, <Picture 2>…
до 9 шт.
modelstring
Модель.
hawklance-4.8 · по умолчанию hawklance-4.8
duration_secondsinteger
Длина ролика. У шаблона своя длина, поле не передаётся.
от 5 до 15 · по умолчанию 5
aspect_ratiostring
Формат. У шаблона — из его aspect_ratios.
9:16, 16:9 · по умолчанию 9:16
qualitystring
Качество. 1080p — скоро.
480p, 720p · по умолчанию 480p
seedinteger
Число для повторяемого результата.
metadataobject
Ваши метки, вернутся в ответе и вебхуке.
simulatestring
Только с тестовым ключом: чем закончится ролик.
success, failed, moderated · по умолчанию success

Ответы

200Повтор с тем же Idempotency-Key: заголовок Idempotent-Replayed: true.
202Видео в очереди.
400Неверное поле: param показывает какое.
401Ключ не передан, неверен или отозван.
402Не хватает токенов или достигнут месячный лимит.
404Такого шаблона нет.
429Превышен лимит запросов или одновременных видео.

curl -X POST https://api.hawklance.ai/v1/videos \
  -H "Authorization: Bearer $HAWKLANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "novyy-obraz",
    "inputs": {
      "person": [
        "file_3Hq9XkLs2VbN7mPz0RtYc4Wd"
      ],
      "new_look": [
        "file_7Bv1NcXz5QwE2rTy8UiOp3As"
      ]
    },
    "quality": "720p",
    "metadata": {
      "order_id": "4815"
    }
  }'

Ответ 200

{
  "id": "vid_8fK2mQxLp0ZrT4nYw7Vb1sDc",
  "object": "video",
  "mode": "test",
  "status": "succeeded",
  "progress": 1,
  "model": "hawklance-4.8",
  "template": "novyy-obraz",
  "prompt": null,
  "inputs": {
    "person": [
      "file_3Hq9XkLs2VbN7mPz0RtYc4Wd"
    ],
    "new_look": [
      "file_7Bv1NcXz5QwE2rTy8UiOp3As"
    ]
  },
  "images": [
    "file_3Hq9XkLs2VbN7mPz0RtYc4Wd",
    "file_7Bv1NcXz5QwE2rTy8UiOp3As"
  ],
  "duration_seconds": 10,
  "aspect_ratio": "9:16",
  "quality": "720p",
  "width": 768,
  "height": 1344,
  "seed": 482910375,
  "cost": {
    "tokens": 390,
    "charged": false
  },
  "estimated_seconds": 12,
  "output": {
    "url": "https://firsts3.ru/hawklance/templates/novyy-obraz/preview.mp4?v=2",
    "poster_url": "https://firsts3.ru/hawklance/templates/novyy-obraz/poster.jpg",
    "expires_at": "2026-11-02T18:04:12.000Z"
  },
  "error": null,
  "metadata": {
    "order_id": "4815"
  },
  "simulated": true,
  "created_at": "2026-11-02T12:04:00.000Z",
  "finished_at": "2026-11-02T12:04:12.000Z"
}

Список видео

get/v1/videos

Видео режима, которому принадлежит ключ.

Параметры

limitinteger
Сколько записей вернуть, от 1 до 100.
от 1 до 100 · по умолчанию 20
afterstring
next_cursor предыдущей страницы.
statusstring
Только видео в этом статусе.
queued, running, succeeded, failed, canceled

Ответы

200Список, новые сверху.
401Ключ не передан, неверен или отозван.

curl https://api.hawklance.ai/v1/videos \
  -H "Authorization: Bearer $HAWKLANCE_API_KEY"

Ответ 200

{
  "object": "list",
  "data": [
    {
      "id": "vid_8fK2mQxLp0ZrT4nYw7Vb1sDc",
      "object": "video",
      "mode": "test",
      "status": "succeeded",
      "progress": 1,
      "model": "hawklance-4.8",
      "template": "novyy-obraz",
      "prompt": null,
      "inputs": {
        "person": [
          "file_3Hq9XkLs2VbN7mPz0RtYc4Wd"
        ],
        "new_look": [
          "file_7Bv1NcXz5QwE2rTy8UiOp3As"
        ]
      },
      "images": [
        "file_3Hq9XkLs2VbN7mPz0RtYc4Wd",
        "file_7Bv1NcXz5QwE2rTy8UiOp3As"
      ],
      "duration_seconds": 10,
      "aspect_ratio": "9:16",
      "quality": "720p",
      "width": 768,
      "height": 1344,
      "seed": 482910375,
      "cost": {
        "tokens": 390,
        "charged": false
      },
      "estimated_seconds": 12,
      "output": {
        "url": "https://firsts3.ru/hawklance/templates/novyy-obraz/preview.mp4?v=2",
        "poster_url": "https://firsts3.ru/hawklance/templates/novyy-obraz/poster.jpg",
        "expires_at": "2026-11-02T18:04:12.000Z"
      },
      "error": null,
      "metadata": {
        "order_id": "4815"
      },
      "simulated": true,
      "created_at": "2026-11-02T12:04:00.000Z",
      "finished_at": "2026-11-02T12:04:12.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Получить видео

get/v1/videos/{id}

Статус и результат. Опрашивайте не чаще раза в 5 секунд или подпишитесь на вебхук.

Параметры

idstringобязательно
Идентификатор видео.

Ответы

200Видео.
401Ключ не передан, неверен или отозван.
404Video не найден(о) или принадлежит другому режиму.

curl https://api.hawklance.ai/v1/videos/vid_... \
  -H "Authorization: Bearer $HAWKLANCE_API_KEY"

Ответ 200

{
  "id": "vid_8fK2mQxLp0ZrT4nYw7Vb1sDc",
  "object": "video",
  "mode": "test",
  "status": "succeeded",
  "progress": 1,
  "model": "hawklance-4.8",
  "template": "novyy-obraz",
  "prompt": null,
  "inputs": {
    "person": [
      "file_3Hq9XkLs2VbN7mPz0RtYc4Wd"
    ],
    "new_look": [
      "file_7Bv1NcXz5QwE2rTy8UiOp3As"
    ]
  },
  "images": [
    "file_3Hq9XkLs2VbN7mPz0RtYc4Wd",
    "file_7Bv1NcXz5QwE2rTy8UiOp3As"
  ],
  "duration_seconds": 10,
  "aspect_ratio": "9:16",
  "quality": "720p",
  "width": 768,
  "height": 1344,
  "seed": 482910375,
  "cost": {
    "tokens": 390,
    "charged": false
  },
  "estimated_seconds": 12,
  "output": {
    "url": "https://firsts3.ru/hawklance/templates/novyy-obraz/preview.mp4?v=2",
    "poster_url": "https://firsts3.ru/hawklance/templates/novyy-obraz/poster.jpg",
    "expires_at": "2026-11-02T18:04:12.000Z"
  },
  "error": null,
  "metadata": {
    "order_id": "4815"
  },
  "simulated": true,
  "created_at": "2026-11-02T12:04:00.000Z",
  "finished_at": "2026-11-02T12:04:12.000Z"
}

Удалить видео

delete/v1/videos/{id}

Удаляет завершённое видео и файл результата. Идущее сначала отмените.

Параметры

idstringобязательно
Идентификатор видео.

Ответы

200Удалено.
401Ключ не передан, неверен или отозван.
404Video не найден(о) или принадлежит другому режиму.
409Видео ещё идёт.

curl -X DELETE https://api.hawklance.ai/v1/videos/vid_... \
  -H "Authorization: Bearer $HAWKLANCE_API_KEY"

Ответ 200

{
  "id": "vid_8fK2mQxLp0ZrT4nYw7Vb1sDc",
  "object": "video",
  "deleted": true
}

Отменить видео

post/v1/videos/{id}/cancel

Останавливает незавершённое видео и возвращает токены.

Параметры

idstringобязательно
Идентификатор видео.

Ответы

200Отменено.
401Ключ не передан, неверен или отозван.
404Video не найден(о) или принадлежит другому режиму.
409Видео уже завершилось.

curl -X POST https://api.hawklance.ai/v1/videos/vid_.../cancel \
  -H "Authorization: Bearer $HAWKLANCE_API_KEY"

Ответ 200

{
  "id": "vid_8fK2mQxLp0ZrT4nYw7Vb1sDc",
  "object": "video",
  "mode": "test",
  "status": "canceled",
  "progress": 0,
  "model": "hawklance-4.8",
  "template": "novyy-obraz",
  "prompt": null,
  "inputs": {
    "person": [
      "file_3Hq9XkLs2VbN7mPz0RtYc4Wd"
    ],
    "new_look": [
      "file_7Bv1NcXz5QwE2rTy8UiOp3As"
    ]
  },
  "images": [
    "file_3Hq9XkLs2VbN7mPz0RtYc4Wd",
    "file_7Bv1NcXz5QwE2rTy8UiOp3As"
  ],
  "duration_seconds": 10,
  "aspect_ratio": "9:16",
  "quality": "720p",
  "width": 768,
  "height": 1344,
  "seed": 482910375,
  "cost": {
    "tokens": 390,
    "charged": false
  },
  "estimated_seconds": 12,
  "output": null,
  "error": null,
  "metadata": {
    "order_id": "4815"
  },
  "simulated": true,
  "created_at": "2026-11-02T12:04:00.000Z",
  "finished_at": "2026-11-02T12:04:12.000Z"
}

Файлы

Фото, видео и аудио для генераций. Файл принадлежит режиму ключа, которым загружен.

Загрузить файл

post/v1/files

Фото и аудио до 25 МБ, видео до 200 МБ. Форматы: JPG, PNG, WebP, HEIC, AVIF; MP4, MOV, WebM; MP3, M4A, AAC, WAV, OGG.

Тело запроса

filestringобязательно
Сам файл.

Ответы

201Файл принят.
400Файла нет в запросе.
401Ключ не передан, неверен или отозван.
413Файл слишком большой.
415Формат не поддерживается.

curl -X POST https://api.hawklance.ai/v1/files \
  -H "Authorization: Bearer $HAWKLANCE_API_KEY" \
  -F file=@portrait.jpg

Ответ 201

{
  "id": "file_3Hq9XkLs2VbN7mPz0RtYc4Wd",
  "object": "file",
  "mode": "test",
  "kind": "image",
  "name": "portrait.jpg",
  "bytes": 482113,
  "content_type": "image/jpeg",
  "created_at": "2026-11-02T12:03:41.000Z"
}

Список файлов

get/v1/files

Файлы режима, которому принадлежит ключ.

Параметры

limitinteger
Сколько записей вернуть, от 1 до 100.
от 1 до 100 · по умолчанию 20

Ответы

200Список, новые сверху.
401Ключ не передан, неверен или отозван.

curl https://api.hawklance.ai/v1/files \
  -H "Authorization: Bearer $HAWKLANCE_API_KEY"

Ответ 200

{
  "object": "list",
  "data": [
    {
      "id": "file_3Hq9XkLs2VbN7mPz0RtYc4Wd",
      "object": "file",
      "mode": "test",
      "kind": "image",
      "name": "portrait.jpg",
      "bytes": 482113,
      "content_type": "image/jpeg",
      "created_at": "2026-11-02T12:03:41.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Получить файл

get/v1/files/{id}

Сведения о загруженном файле.

Параметры

idstringобязательно
Идентификатор файла.

Ответы

200Файл.
401Ключ не передан, неверен или отозван.
404File не найден(о) или принадлежит другому режиму.

curl https://api.hawklance.ai/v1/files/file_... \
  -H "Authorization: Bearer $HAWKLANCE_API_KEY"

Ответ 200

{
  "id": "file_3Hq9XkLs2VbN7mPz0RtYc4Wd",
  "object": "file",
  "mode": "test",
  "kind": "image",
  "name": "portrait.jpg",
  "bytes": 482113,
  "content_type": "image/jpeg",
  "created_at": "2026-11-02T12:03:41.000Z"
}

Шаблоны

Каталог трендов и поля, которые нужны каждому шаблону.

Список шаблонов

get/v1/templates

Весь открытый каталог. Обновляется: держите id шаблонов в настройках, а не в коде.

Параметры

limitinteger
Сколько записей вернуть, от 1 до 100.
от 1 до 100 · по умолчанию 20
afterstring
next_cursor предыдущей страницы.
sectionstring
Только шаблоны этого раздела.

Ответы

200Список, новые сверху.
401Ключ не передан, неверен или отозван.

curl https://api.hawklance.ai/v1/templates \
  -H "Authorization: Bearer $HAWKLANCE_API_KEY"

Ответ 200

{
  "object": "list",
  "data": [
    {
      "id": "novyy-obraz",
      "object": "template",
      "name": "Новый образ",
      "section": "UGC-контент",
      "description": "Смена образа по щелчку: было — стало.",
      "duration_seconds": 10,
      "aspect_ratios": [
        "9:16"
      ],
      "poster_url": "https://firsts3.ru/hawklance/templates/novyy-obraz/poster.jpg",
      "preview_url": "https://firsts3.ru/hawklance/templates/novyy-obraz/preview.mp4?v=2",
      "inputs": [
        {
          "name": "person",
          "type": "images",
          "title": "Ваше фото ДО",
          "description": "По пояс или в полный рост, лицо хорошо видно, один человек.",
          "required": true,
          "min_count": 1,
          "max_count": 1
        },
        {
          "name": "new_look",
          "type": "images",
          "title": "Ваш новый образ",
          "description": "Вы в новом наряде или сам наряд целиком.",
          "required": true,
          "min_count": 1,
          "max_count": 1
        }
      ]
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Получить шаблон

get/v1/templates/{id}

Поля inputs показывают, что передать в POST /videos.

Параметры

idstringобязательно
Идентификатор шаблона.

Ответы

200Шаблон.
401Ключ не передан, неверен или отозван.
404Такого шаблона нет.

curl https://api.hawklance.ai/v1/templates/novyy-obraz \
  -H "Authorization: Bearer $HAWKLANCE_API_KEY"

Ответ 200

{
  "id": "novyy-obraz",
  "object": "template",
  "name": "Новый образ",
  "section": "UGC-контент",
  "description": "Смена образа по щелчку: было — стало.",
  "duration_seconds": 10,
  "aspect_ratios": [
    "9:16"
  ],
  "poster_url": "https://firsts3.ru/hawklance/templates/novyy-obraz/poster.jpg",
  "preview_url": "https://firsts3.ru/hawklance/templates/novyy-obraz/preview.mp4?v=2",
  "inputs": [
    {
      "name": "person",
      "type": "images",
      "title": "Ваше фото ДО",
      "description": "По пояс или в полный рост, лицо хорошо видно, один человек.",
      "required": true,
      "min_count": 1,
      "max_count": 1
    },
    {
      "name": "new_look",
      "type": "images",
      "title": "Ваш новый образ",
      "description": "Вы в новом наряде или сам наряд целиком.",
      "required": true,
      "min_count": 1,
      "max_count": 1
    }
  ]
}

Модели

Доступные модели и их возможности.

Список моделей

get/v1/models

Модели и их возможности.

Ответы

200Список, новые сверху.
401Ключ не передан, неверен или отозван.

curl https://api.hawklance.ai/v1/models \
  -H "Authorization: Bearer $HAWKLANCE_API_KEY"

Ответ 200

{
  "object": "list",
  "data": [
    {
      "id": "hawklance-4.8",
      "object": "model",
      "name": "Hawklance 4.8",
      "description": "Видео со звуком по описанию, фото и шаблонам трендов.",
      "qualities": [
        "480p",
        "720p"
      ],
      "coming_soon_qualities": [
        "1080p"
      ],
      "aspect_ratios": [
        "9:16",
        "16:9"
      ],
      "max_duration_seconds": 15,
      "max_images": 9,
      "sound": true
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Баланс

Остаток токенов и лимиты аккаунта.

Получить баланс

get/v1/balance

Токены на балансе, расход за месяц, лимиты и цена секунды.

Ответы

200Баланс.
401Ключ не передан, неверен или отозван.

curl https://api.hawklance.ai/v1/balance \
  -H "Authorization: Bearer $HAWKLANCE_API_KEY"

Ответ 200

{
  "object": "balance",
  "tokens": 22590,
  "month_spend_tokens": 7410,
  "monthly_limit_tokens": 100000,
  "tier": "tier-1",
  "tokens_per_second": {
    "480p": 29,
    "720p": 39
  }
}

Объекты

Видео

Поля

idstringобязательно
Начинается с vid_.
object"video"обязательно
modestringобязательно
Режим ключа.
test, live
statusstringобязательно
queued → running → succeeded, failed или canceled.
queued, running, succeeded, failed, canceled
progressnumberобязательно
Доля готовности.
от 0 до 1
modelstringобязательно
templatestringобязательно
promptstringобязательно
Ваше описание. Описание шаблона не показывается.
inputsobject
imagesstring[]обязательно
duration_secondsnumberобязательно
aspect_ratiostringобязательно
qualitystringобязательно
widthintegerобязательно
heightintegerобязательно
seedintegerобязательно
costobjectобязательно
tokensintegerобязательно
Цена ролика.
chargedbooleanобязательно
Списаны ли токены сейчас.
estimated_secondsintegerобязательно
Сколько примерно займёт генерация с момента создания.
outputobjectобязательно
urlstringобязательно
Ссылка на MP4.
poster_urlstringобязательно
Ссылка на постер.
expires_atstringобязательно
Ссылка действует 6 часов; свежую даст новый запрос.
errorobjectобязательно
codestringобязательно
messagestringобязательно
metadataobjectобязательно
simulatedbooleanобязательно
true — рендер эмулируется, в output лежит пример. Пропадёт, когда рендер подключат.
created_atstringобязательно
finished_atstringобязательно

Шаблон

Поля

idstringобязательно
object"template"обязательно
namestringобязательно
sectionstringобязательно
descriptionstringобязательно
duration_secondsnumberобязательно
aspect_ratiosstring[]обязательно
poster_urlstringобязательно
preview_urlstringобязательно
inputsobject[]обязательно
Поля шаблона.

Файл

Поля

idstringобязательно
Начинается с file_.
object"file"обязательно
modestringобязательно
test, live
kindstringобязательно
image, audio, video
namestringобязательно
bytesintegerобязательно
content_typestringобязательно
created_atstringобязательно