API генерации

APIClaw Generation API для асинхронных задач изображений и видео

Используйте Generation API, когда продукту нужен стабильный процесс отправки задач изображений или видео, проверки статуса и загрузки исходных материалов.

Обзор API

• Базовый URL: https://www.apiclaw.net — Используйте origin вашего APIClaw deployment или server address, показанный в аккаунте.
• Аутентификация: Authorization: Bearer $YOUR_API_KEY — Создайте API key в консоли и отправляйте его как Bearer token.
• Обертка ответа: { code, message, data } — Успешные ответы возвращают code, message и типизированный data payload.

API-эндпоинты

Каждый процесс генерации устроен одинаково: отправьте задачу, проверяйте ее статус и загружайте материалы, если модели нужен вход с изображением.

• POST /v2/images/generations — Отправить image task. Создает асинхронную задачу генерации изображения.
• POST /v2/videos/generations — Отправить video task. Создает асинхронную задачу генерации видео.
• GET /v2/tasks/{task_id} — Запросить задачу. Опрашивайте, пока задача не достигнет финального статуса.
• POST /v2/upload — Загрузить файл. Загрузите image asset и используйте возвращенный URL в запросе генерации.

Шаг 1

Отправить задачу генерации изображения или видео

Отправьте JSON в эндпоинт генерации изображений или видео. В ответе будет task_id для проверки прогресса. Видео-модели могут использовать текст, изображения, видео и параметры extra в зависимости от выбранного семейства.

POST /v2/images/generations POST /v2/videos/generations

Поле

Пример

curl https://www.apiclaw.net/v2/videos/generations \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling/kling-v3-omni",
    "prompt": "Put the jewelry from the reference image on the person in the video",
    "videos": ["https://cdn.example.com/source.mp4"],
    "images": ["https://cdn.example.com/ref.png"],
    "duration": 8,
    "resolution": "std",
    "extra": {
      "referType": "base"
    }
  }'

Запрос отправки

{
  "model": "kling/kling-v3-omni",
  "prompt": "Put the jewelry from the reference image on the person in the video",
  "videos": [
    "https://cdn.example.com/source.mp4"
  ],
  "images": [
    "https://cdn.example.com/ref.png"
  ],
  "duration": 8,
  "resolution": "std",
  "extra": {
    "referType": "base"
  }
}

Ответ отправки

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_01JXYZ9Y8K6G3R4S5T6V7W8X9Y",
    "status": "submitted"
  }
}

Заметки

• Откройте страницу модели, чтобы посмотреть параметры запроса для этой модели.
• Генерация изображений и видео выполняется асинхронно, даже если результат появляется быстро.
• Для редактирования исходного видео в Kling отправляйте videos и extra.referType = "base"; для обычных ссылок на изображения отправляйте только images.

Шаг 2

Запрашивать статус задачи до финального состояния

Опрашивайте task endpoint с task_id из submit. Остановитесь, когда status станет completed, failed, cancelled или canceled.

GET /v2/tasks/{task_id}

Поле

Пример

curl https://www.apiclaw.net/v2/tasks/task_01JXYZ9Y8K6G3R4S5T6V7W8X9Y \
  -H "Authorization: Bearer $YOUR_API_KEY"

Запрос статуса

{
  "method": "GET",
  "path": "/v2/tasks/task_01JXYZ9Y8K6G3R4S5T6V7W8X9Y"
}

Ответ completed

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "task_01JXYZ9Y8K6G3R4S5T6V7W8X9Y",
    "task_id": "task_01JXYZ9Y8K6G3R4S5T6V7W8X9Y",
    "status": "completed",
    "progress": 100,
    "result": {
      "videos": [
        {
          "url": "https://cdn.example.com/result.mp4",
          "thumbnail_url": "https://cdn.example.com/cover.jpg"
        }
      ],
      "images": [
        {
          "url": "https://cdn.example.com/result.png"
        }
      ]
    },
    "error": null
  }
}

Заметки

• Используйте exponential backoff или короткий фиксированный интервал, чтобы избежать лишнего polling.
• Считайте failed, cancelled и canceled терминальными состояниями.

Шаг 3

Загрузить исходные assets для workflows с image input

Загружайте изображения перед отправкой image-to-video или reference workflows. Используйте возвращенный URL в image_url или другом поле конкретной модели.

POST /v2/upload

Поле

Пример

curl https://www.apiclaw.net/v2/upload \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -F "file=@./source.png"

Запрос загрузки

{
  "content_type": "multipart/form-data",
  "field": "file"
}

Ответ загрузки

{
  "cosKey": "uploads/2026/06/source.png",
  "url": "https://cdn.example.com/source.png",
  "mimeType": "image/png",
  "fileSize": 245760
}

Заметки

• Не задавайте Content-Type вручную для multipart uploads в браузере; FormData сама задаст boundary.
• Используйте загруженный URL с моделями, которые принимают изображение на вход.

Параметры модели

Generation API использует единый поток задач для разных моделей, но параметры запроса могут отличаться. Перед продакшеном откройте страницу модели и проверьте поля, лимиты и примеры.

APIClaw