---
title: Async Command Runner
emoji: 🏃
colorFrom: indigo
colorTo: blue
sdk: docker
pinned: false
---

# API для выполнения команд

Это API позволяет удаленно выполнять консольные команды. Поддерживается два режима:

1.  **Потоковый (Stream)**: Быстрая обработка "на лету" для простых команд.
2.  **Асинхронные задачи (Tasks)**: Для длительных операций, с возможностью отслеживания прогресса.

---

## Режим 1: Потоковая обработка

Идеально для быстрых команд. Файл передается в `stdin` команды, а результат из `stdout` возвращается клиенту. Файлы не сохраняются на диске.

**Эндпоинт:** `POST /api/run/stream`

**Пример `curl`:**
```bash
curl -X POST 'https://<your-space-url>/api/run/stream' \
-F 'file=@/path/to/your/image.jpg' \
-F 'command=magick' \
-F 'args=["convert", "-", "-grayscale", "average", "jpg:-"]' \
--output grayscale_image.jpg

Режим 2: Асинхронные задачи
Используйте, когда команде нужно работать с файлами на диске или когда результат нужно сохранить.
Шаг 1: Создание задачи
Эндпоинт: POST /api/task/create
Пример curl:
curl -X POST 'https://<your-space-url>/api/task/create' \
-F 'command=ffmpeg' \
-F 'args=["-i", "{INPUT_FILE}", "-vcodec", "libx264", "-acodec", "aac", "{OUTPUT_FILE}"]' \
-F 'file=@"/path/to/your/video.mov"' \
-F 'output_filename=converted.mp4'

Ответ сервера (статус 202 Accepted):
{
    "message": "Task accepted.",
    "taskId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status_url": "/api/task/status/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Шаг 2: Проверка статуса задачи
Эндпоинт: GET /api/task/status/:taskId
Отправляйте GET-запросы на status_url, чтобы отслеживать выполнение.
Пример ответа (завершено):
{
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "completed",
    "elapsedTimeSeconds": 60,
    "result": {
        "download_url": "/api/download/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy-converted.mp4"
    }
}

Шаг 3: Скачивание результата
Когда задача получает статус completed, используйте download_url для скачивания файла.
Эндпоинт: GET /api/download/:fileId
curl 'https://<your-space-url>/api/download/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy-converted.mp4' \
--output "final_video.mp4"