WaveSpeedAI
← Блог

Как использовать claw-code с моделями WaveSpeed AI через API

Узнайте, как интегрировать модели генерации изображений и видео в агентный рабочий процесс claw-code с помощью единого API моделей.

10 min read
Как использовать claw-code с моделями WaveSpeed AI через API

Представьте: ваш ИИ-агент не просто думает — он создаёт.

Он рассуждает шаг за шагом, затем бесшовно вызывает мощную модель генерации изображений для создания потрясающей графики, переключается на видеомодель для анимации, анализирует результаты и продолжает рабочий процесс — всё это без единого нажатия клавиши с вашей стороны и без переписывания кода.

Именно это теперь возможно с моделями WaveSpeed AI и claw-code — переписанным с нуля на Python в стиле clean-room и опубликованным в открытом доступе корейским разработчиком сразу после утечки исходного кода Claude Code.

В этом руководстве вы узнаете, как использовать это мощное сочетание для создания агентов, которые не просто общаются… они создают, итерируют и производят реальный мультимедийный контент внутри единого интеллектуального цикла.

Если вы создатель, разработчик или ИИ-энтузиаст, которому надоело переключаться между инструментами — это ваш путь к по-настоящему агентным мультимедийным рабочим процессам.

Готовы сделать ваших ИИ-агентов визуально мощными? Приступим.

Предварительные требования: что нужно подготовить

Прежде чем трогать хоть одну строку конфига, разберитесь с двумя вещами. Пропуск любой из них обойдётся вам часами загадочных сообщений об ошибках.

Настройка claw-code и окружения

claw-code работает на Python 3.11+. По состоянию на март 2026 года основная ветка ориентирована на Python (72,9% Rust, 27,1% Python согласно собственной разбивке проекта по языкам, однако CLI-точка входа, которой вы будете пользоваться ежедневно, написана на Python). Установите из официального репозитория:

git clone https://github.com/instructkr/claw-code.git
cd claw-code
pip install -e .

Также потребуется задать ключ Anthropic в переменной окружения — claw-code поддерживает и ANTHROPIC_API_KEY, и ANTHROPIC_AUTH_TOKEN, следуя паттернам аутентификации Anthropic API из официальной документации.

export ANTHROPIC_API_KEY="your-key-here"

Важное замечание: порт на Rust всё ещё в разработке на отдельной ветке. Для видео- и изображений Python-обвязка достаточно стабильна. Миграция на Rust направлена на производительно-критичные пути выполнения — для данного сценария использования это пока не нужно.

API-ключ и доступ к провайдеру моделей

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

Каталог моделей WaveSpeed по состоянию на март 2026 года насчитывает 700+ моделей для генерации изображений, видео, аудио и 3D — все за одним унифицированным API-ключом. Это очень важно, как только вы начнёте строить агентные рабочие процессы с несколькими моделями: не придётся управлять пятью разными заголовками авторизации.

Подключение внешних API моделей в рабочем процессе claw-code

Вот где начинается самое интересное. claw-code — это не просто ассистент по программированию; он реализует полноценный уровень выполнения инструментов с 19 инструментами с контролем доступа и моделью плагинов, которую можно расширять. Именно это делает подключение внешнего API, такого как WaveSpeed, по-настоящему реализуемым.

Как claw-code обрабатывает вызовы внешних инструментов

Система инструментов claw-code работает через определения JSON-схем, генерируемые в слое Rust, тогда как Python обрабатывает оркестрацию агента. Каждый инструмент имеет собственные права доступа, определённые в permissions.py. Когда вы добавляете пользовательский инструмент, агент может автономно решить, когда его вызвать, исходя из контекста задачи — что именно и нужно, когда промпт «напиши скрипт и сгенерируй подходящую миниатюру» должен запустить и текстовую задачу, и вызов генерации изображения.

Логика повторных попыток, встроенная в Anthropic API-клиент claw-code, использует экспоненциальную задержку для ответов 408, 429 и 5xx. Этот же паттерн вы будете воспроизводить для вызовов WaveSpeed.

Добавление API модели как инструмента в обвязку

Создайте файл wavespeed_tool.py в директории инструментов claw-code:

import httpx
import os
import time

WAVESPEED_API_KEY = os.environ.get("WAVESPEED_API_KEY")
BASE_URL = "https://api.wavespeed.ai/api/v3"

TOOL_SCHEMA = {
    "name": "generate_image",
    "description": "Generate an image using WaveSpeed AI given a text prompt.",
    "input_schema": {
        "type": "object",
        "properties": {
            "prompt": {"type": "string", "description": "Image generation prompt"},
            "model": {"type": "string", "default": "wavespeed-ai/flux-dev"},
        },
        "required": ["prompt"],
    },
}

def generate_image(prompt: str, model: str = "wavespeed-ai/flux-dev") -> dict:
    headers = {"Authorization": f"Bearer {WAVESPEED_API_KEY}"}
    payload = {"inputs": {"prompt": prompt}, "enable_safety_checker": True}
    response = httpx.post(f"{BASE_URL}/{model}/run", json=payload, headers=headers)
    response.raise_for_status()
    return response.json()

Зарегистрируйте это в реестре инструментов claw-code — и агент сможет вызывать generate_image в любой сессии, где создание изображений входит в область задач.

Вызов моделей генерации изображений и видео внутри агентного рабочего процесса

Это тот раздел, который я так хотел найти при первоначальной настройке — и не смог. Вот он, написанный максимально доступно.

Паттерн вызова REST API

WaveSpeed использует единый REST-паттерн для всех моделей. Базовый вызов выглядит так (на примере WAN 2.7 text-to-video):

import httpx

def call_wavespeed(model_id: str, inputs: dict) -> dict:
    headers = {
        "Authorization": f"Bearer {os.environ['WAVESPEED_API_KEY']}",
        "Content-Type": "application/json",
    }
    payload = {"inputs": inputs}
    response = httpx.post(
        f"https://api.wavespeed.ai/api/v3/{model_id}/run",
        json=payload,
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

Для изображений (например, Flux Dev или Seedream v4.5) ответ возвращается синхронно с URL вывода. Для видеомоделей — WAN 2.7, Kling 2.6, Hailuo 2.3 — запрос асинхронный, что означает необходимость опроса статуса.

Обработка асинхронной генерации и опроса

Генерация видео на WaveSpeed обычно занимает от 30 секунд до нескольких минут в зависимости от модели и длительности. API немедленно возвращает request_id; вы опрашиваете эндпоинт статуса до завершения задачи.

def poll_until_done(request_id: str, max_wait: int = 300) -> dict:
    headers = {"Authorization": f"Bearer {os.environ['WAVESPEED_API_KEY']}"}
    start = time.time()
    
    while time.time() - start < max_wait:
        resp = httpx.get(
            f"https://api.wavespeed.ai/api/v3/predictions/{request_id}/status",
            headers=headers,
        )
        data = resp.json()
        status = data.get("status")
        
        if status == "completed":
            return data
        elif status == "failed":
            raise RuntimeError(f"Generation failed: {data.get('error')}")
        
        time.sleep(5)  # Опрос каждые 5 секунд
    
    raise TimeoutError("Generation timed out")

Внутри цикла агента claw-code этот опрос следует обернуть в функцию выполнения инструмента, чтобы агент ожидал результата перед переходом к следующему шагу.

Управление лимитами запросов и резервными вариантами в агентном контексте

Лимиты запросов внутри цикла агента сложнее, чем в простом скрипте — агент может отправить несколько вызовов инструментов подряд, если задача допускает параллелизацию. Вот паттерн с резервными вариантами, адаптированный из собственной логики повторов claw-code:

import time

def call_with_retry(model_id: str, inputs: dict, retries: int = 3) -> dict:
    fallback_models = {
        "wavespeed-ai/wan-2.7-t2v": "wavespeed-ai/wan-2.6-t2v",
    }
    
    for attempt in range(retries):
        try:
            return call_wavespeed(model_id, inputs)
        except httpx.HTTPStatusError as e:
            if e.response.status_code == 429:
                wait = 2 ** attempt  # Экспоненциальная задержка
                time.sleep(wait)
            elif e.response.status_code >= 500:
                # Попробовать резервную модель, если доступна
                model_id = fallback_models.get(model_id, model_id)
                time.sleep(2)
            else:
                raise
    raise RuntimeError(f"All retries exhausted for {model_id}")

Документация WaveSpeed API подробно описывает уровни лимитов запросов по типу аккаунта — Silver-аккаунты (разовое пополнение на $100) получают существенно более высокие лимиты параллелизма по сравнению с Bronze-уровнем по умолчанию, что важно, когда ваши агенты начинают отправлять несколько запросов на генерацию за сессию.

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

Хочу остановиться на том, почему эта архитектура стоит затраченных усилий — потому что это неочевидно, пока вы не столкнётесь с реальными трудностями управления отдельными API-аккаунтами для каждой модели.

Переключение между моделями без переписывания рабочего процесса

Унифицированный API WaveSpeed означает, что вы можете заменить wavespeed-ai/flux-dev на wavespeed-ai/seedream-v4-5 одним изменением строки. Никакого нового процесса авторизации, никакой другой схемы ответа для разбора, никакой смены SDK. Для агентного рабочего процесса, где агент должен выбирать подходящую модель под задачу (фотореалистичная миниатюра, стилизованная иллюстрация или короткий видеоклип), это по-настоящему полезно — можно передавать ID модели как переменную и позволить агенту самому рассуждать о том, какая подходит лучше.

Вот простая таблица сравнения моделей на основе спецификаций генерации за март 2026 года из каталога WaveSpeed:

МодельТипВыводЛучше всего для
Flux DevИзображениеДо 4KФотореализм, высокая скорость
Seedream v4.5ИзображениеДо 4KХудожественный, стилизованный
WAN 2.7 T2VВидео720p/1080pТекст в видео, кинематографичность
Kling 2.6 ProВидео720pУправление движением, анимация
Hailuo 2.3 FastВидео720pСкоростная I2V

Единая биллинг и управление ключами

Это оказалось более значимым, чем я ожидал. Управление отдельными API-ключами для Runway, Kling, FLUX и WAN по отдельности — каждый со своей панелью биллинга, своим поведением лимитов, своими форматами ошибок — создаёт ощутимую операционную нагрузку при разработке агентных рабочих процессов. Один ключ, одна панель биллинга и согласованные схемы ошибок для всех моделей — это реальное повышение удобства, которое сказывается на сопровождаемости кода агента со временем.

Перед развёртыванием сторонних агентов в продакшне стоит ознакомиться с руководством OWASP по безопасности программной цепочки поставок — особенно актуально с учётом инцидента с цепочкой поставок, затронувшего npm-установки Claude Code в марте 2026 года (claw-code сам по себе не был затронут, но более широкая экосистема требует осторожности).

Ограничения и вещи, требующие проверки

Было бы нечестно пропустить шероховатые места.

Оговорки о стабильности claw-code

По состоянию на апрель 2026 года claw-code не имеет паритета функций с Claude Code. Порт на Rust всё ещё в разработке. Интеграции с IDE отсутствуют — только терминал. Оркестрация нескольких агентов задокументирована в архитектуре, но не прошла боевого тестирования в масштабе. У проекта 48k+ звёзд на GitHub и он развивается быстро, однако «интересная архитектура» и «готовность к продакшну» — это принципиально разные планки.

Правовой статус проекта также не урегулирован. claw-code заявляет о статусе clean-room как своей защите от давления Anthropic через DMCA — это переписанный проект, а не копия утёкших исходников, — но этот юридический вопрос не решён. Если вы строите что-то для клиента или в масштабе, учитывайте эту неопределённость.

Что требует ручного тестирования

Прежде чем доверять этому рабочему процессу в продакшне, следует вручную проверить:

  • Поведение при тайм-ауте опроса: интервал опроса в 5 секунд, который я использую, консервативный. Протестируйте с вашей реальной видеомоделью и длительностью, чтобы подобрать max_wait.
  • Регистрация инструментов: реестр инструментов claw-code активно разрабатывается. Точный API регистрации может меняться между коммитами — проверяйте CHANGELOG репозитория перед фиксацией версии.
  • Контекст разрешений: claw-code реализует выполнение инструментов с контролем доступа. Убедитесь, что вашим инструментам generate_image и generate_video предоставлен правильный уровень доступа в permissions.py.
  • Изменения схемы ответа: WaveSpeed периодически обновляет схемы вывода моделей. Добавьте валидацию для поля URL вывода, а не полагайтесь на предположение о структуре.

FAQ

В: Может ли claw-code вызывать API генерации изображений нативно?

Из коробки — нет: в стандартной установке нет встроенного инструмента WaveSpeed или генерации изображений. Но система инструментов разработана именно для такого рода расширений. После регистрации пользовательского инструмента с правильной JSON-схемой (как показано выше) агент сможет вызывать его автономно в любой сессии.

В: Поддерживает ли claw-code асинхронные вызовы инструментов?

Python-обвязка обрабатывает выполнение инструментов синхронно внутри цикла агента. Для асинхронной генерации (например, видеомодели) рекомендуемый паттерн: отправить начальный запрос, получить request_id, затем опрашивать статус внутри функции выполнения инструмента до завершения — и только после этого возвращать управление агенту. Это сохраняет линейность рассуждений агента и позволяет избежать гонок состояний в сессии.

В: Готов ли этот рабочий процесс к продакшну?

Честно? Пока нет, для большинства команд. claw-code развивается быстро, но несёт правовую неопределённость и не прошёл закалку для агентного использования в продакшн-масштабе. Сторона WaveSpeed API готова к продакшну — SLA 99,99% uptime, без холодных стартов, биллинг посекундно — но обвязка claw-code вокруг неё всё ещё на раннем этапе. Я бы использовал это для внутреннего инструментария, прототипирования и исследований прямо сейчас, и вернулся бы к вопросу продакшн-использования для клиентов, когда проект стабилизируется.

Предыдущие материалы:

Поделиться