WaveSpeedAI
← Блог

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

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

By Dora11 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}", 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}",
        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; вы опрашиваете эндпоинт статуса до завершения задачи.

import os
import time
import httpx

TRANSIENT = {429, 500, 502, 503, 504}


def poll_until_done(request_id: str) -> dict:
    headers = {"Authorization": f"Bearer {os.environ['WAVESPEED_API_KEY']}"}
    url = f"https://api.wavespeed.ai/api/v3/predictions/{request_id}/result"
    failures = 0

    while True:
        try:
            resp = httpx.get(url, headers=headers, timeout=30)
        except httpx.TransportError:  # network error or per-request timeout
            resp = None

        if resp is None or resp.status_code in TRANSIENT:
            failures += 1
            retry_after = resp.headers.get("Retry-After", "") if resp is not None else ""
            time.sleep(int(retry_after) if retry_after.isdigit() else min(2 ** failures, 60))
            continue
        if resp.status_code != 200:
            raise RuntimeError(f"Task {request_id}: unexpected HTTP {resp.status_code}")
        failures = 0

        data = resp.json()["data"]
        status = data.get("status")
        if status == "completed":
            return data
        if status in {"failed", "cancelled", "timeout", "deleted"}:
            raise RuntimeError(f"Task {request_id} {status}: {data.get('error')}")

        time.sleep(2)  # poll every 2 seconds

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

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

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

import httpx

FALLBACK_MODELS = {
    "wavespeed-ai/wan-2.7-t2v": "wavespeed-ai/wan-2.6-t2v",
}


def submit_once(model_id: str, inputs: dict) -> str:
    """Send the submit POST exactly once and return the task id."""
    try:
        return call_wavespeed(model_id, inputs)["data"]["id"]
    except httpx.HTTPStatusError as e:
        if e.response.status_code < 500:
            raise  # 4xx: the request was rejected, no task was created
        unknown = e
    except httpx.HTTPError as e:  # timeout, dropped connection, no response
        unknown = e
    raise RuntimeError(
        f"Submit to {model_id} has an unknown outcome ({unknown!r}). A task may "
        "exist and be billed: check History in the WaveSpeed dashboard before resubmitting."
    ) from unknown


def generate(model_id: str, inputs: dict) -> dict:
    try:
        task_id = submit_once(model_id, inputs)
    except httpx.HTTPStatusError as e:
        fallback = FALLBACK_MODELS.get(model_id)
        # Only a 429 is a clear "not accepted" signal; try the fallback once.
        if e.response.status_code != 429 or fallback is None:
            raise
        task_id = submit_once(fallback, inputs)
    return poll_until_done(task_id)

Главное правило: никогда не повторяйте автоматически POST для отправки задачи. Если он завершился ошибкой 5xx или истёк по таймауту, вы не знаете, была ли задача создана (и оплачена), поэтому проверьте историю (History) в панели WaveSpeed, прежде чем отправлять снова. Безопасно действовать можно только при явном отклонении, например 429, — тогда задача не создана. Запросы опроса GET можно повторять без риска: они переживают временные ошибки и продолжаются, пока задача не достигнет конечного статуса.

Документация 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 вокруг неё всё ещё на раннем этапе. Я бы использовал это для внутреннего инструментария, прототипирования и исследований прямо сейчас, и вернулся бы к вопросу продакшн-использования для клиентов, когда проект стабилизируется.

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

Поделиться