PixVerse V6 Reference to Video API: элементы @name

pixverse/v6/reference-to-video

PixVerse V6 reference-to-video, режим Fusion от PixVerse, собирает клип длиной от 1 до 15 секунд из до 7 именованных персонажей и фонов, которых вы вызываете через @name в промпте.

От $0.022/с

Запустить модель Открыть API

Отправить запрос

Примеры используют публичные параметры выбранного эндпоинта. Замените API-ключ и примеры медиафайлов, затем отправьте запрос со своего сервера.

SDK и интеграции

POSThttps://api.spicyapi.ai/api/v1/jobs/createTask

Аутентификация API

Храните API-ключ в серверной переменной окружения SPICY_API_KEY. Используйте Bearer-аутентификацию и Content-Type: application/json для JSON-запросов.

Authorization: Bearer $SPICY_API_KEY

Пример результата

# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  -d '{
  "model": "pixverse/v6/reference-to-video",
  "input": {
    "prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
    "elements": [
      {
        "name": "example",
        "image_url": "https://example.com/reference.png"
      }
    ],
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": false,
    "duration_seconds": 5
  }
}'

# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
  -H "Authorization: Bearer $SPICY_API_KEY"

Пример построен по входной схеме этой модели — той же, по которой API проверяет каждый запрос.

Входные параметры

Поместите эти поля в объект input тела запроса. Имена и типы соответствуют API. Не предполагайте значение по умолчанию, если оно не задано.

elementsarray<object>Обязательно

Обязательно, от 1 до 7 элементов. У каждого есть name (от 1 до 30 символов, слово, которое вы пишете в промпте), image_url с одним изображением этого персонажа или места и role: subject (по умолчанию; человек, животное, предмет или продукт) или background (место или обстановка). Пишите @name в промпте с пробелом после него.

По умолчанию: Не задано
Ограничения: minItems:1
maxItems:7

promptstringОбязательно

Обязательно, от 3 до 5 000 символов. Пишите @name там, где элемент должен появиться, с пробелом после него: в нашем тесте "@trailer," была отклонена, а "@trailer and" сработала. Затем опишите действие и камеру.

По умолчанию: Не задано
Ограничения: minLength:3
maxLength:5000

seedintegerНеобязательно

Необязательное целое число от 0 до 2147483647. Помогает сравнивать запуски при изменении одного параметра; не гарантирует одинаковых кадров.

По умолчанию: Не задано
Ограничения: minimum:0
maximum:2147483647

generate_audiobooleanНеобязательноВлияет на цену

По умолчанию выключено. Когда включено, генерирует звук вместе с картинкой: атмосферу, эффекты, музыку и реплики в кавычках. Со звуком секунда стоит дороже.

По умолчанию: false

duration_secondsintegerНеобязательноВлияет на цену

Целые секунды от 1 до 15 (по умолчанию 5). Оплата за секунду.

По умолчанию: 5
Ограничения: minimum:1
maximum:15

resolutionstringНеобязательноВлияет на цену

360p, 540p, 720p (по умолчанию) или 1080p. Более высокие разрешения стоят дороже за секунду.

По умолчанию: "720p"
Допустимые значения: "360p""540p""720p""1080p"

aspect_ratiostringНеобязательно

16:9 (по умолчанию), 4:3, 1:1, 3:4, 9:16, 2:3, 3:2 или 21:9. Цену не меняет.

По умолчанию: "16:9"
Допустимые значения: "16:9""4:3""1:1""3:4""9:16""2:3""3:2""21:9"

{
  "type": "object",
  "required": [
    "elements",
    "prompt"
  ],
  "x-pricing": {
    "billingMode": "variant_matrix",
    "variantFields": [
      "resolution",
      "generate_audio"
    ]
  },
  "properties": {
    "seed": {
      "type": "integer",
      "x-ui": {
        "order": 10,
        "widget": "number"
      },
      "maximum": 2147483647,
      "minimum": 0,
      "description": "Random seed for controlled comparisons."
    },
    "prompt": {
      "type": "string",
      "x-ui": {
        "order": 100,
        "widget": "textarea",
        "primary": true,
        "reference_tokens": {
          "elements": "@{name}"
        }
      },
      "maxLength": 5000,
      "minLength": 3,
      "description": "Describe the shot and place each reference with @name."
    },
    "elements": {
      "type": "array",
      "x-ui": {
        "order": 87,
        "widget": "object-list"
      },
      "items": {
        "type": "object",
        "required": [
          "name",
          "image_url"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 30,
            "minLength": 1,
            "description": "Name to write as @name in the prompt, up to 30 characters."
          },
          "role": {
            "enum": [
              "subject",
              "background"
            ],
            "type": "string",
            "default": "subject",
            "description": "subject for a person, animal, object or product; background for a place."
          },
          "image_url": {
            "type": "string",
            "format": "uri",
            "description": "One picture of this subject or place."
          }
        },
        "additionalProperties": false
      },
      "maxItems": 7,
      "minItems": 1,
      "description": "One to seven named references. Write @name in the prompt, followed by a space, where each should appear."
    },
    "resolution": {
      "enum": [
        "360p",
        "540p",
        "720p",
        "1080p"
      ],
      "type": "string",
      "x-ui": {
        "order": 70,
        "widget": "radio",
        "affects_price": true
      },
      "default": "720p",
      "description": "Output resolution. Higher tiers cost more per second."
    },
    "aspect_ratio": {
      "enum": [
        "16:9",
        "4:3",
        "1:1",
        "3:4",
        "9:16",
        "2:3",
        "3:2",
        "21:9"
      ],
      "type": "string",
      "x-ui": {
        "order": 80,
        "widget": "select"
      },
      "default": "16:9",
      "description": "Output aspect ratio."
    },
    "generate_audio": {
      "type": "boolean",
      "x-ui": {
        "order": 50,
        "widget": "switch",
        "affects_price": true
      },
      "default": false,
      "description": "Generate sound with the picture. Costs more per second when on."
    },
    "duration_seconds": {
      "type": "integer",
      "x-ui": {
        "step": 1,
        "unit": "s",
        "order": 60,
        "widget": "slider",
        "affects_price": true
      },
      "default": 5,
      "maximum": 15,
      "minimum": 1,
      "description": "Clip length in whole seconds, 1 to 15. Billed per second."
    }
  },
  "additionalProperties": false
}

Отследить задачу

HTTP 202 означает принятие задачи, а не завершение генерации. Сохраните полученный taskId и проверяйте эту задачу. Не создавайте новую, пока ждёте результат.

Ответ при приёме задачи

HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3

{
  "code": 200,
  "msg": "success",
  "request_id": "req_example_create",
  "data": {
    "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "state": "queued",
    "estimatedCost": "0.750000"
  }
}

В ответе о приёме есть оценка стоимости — приложение сможет показать ту же сумму в истории задач и в расчётах.

Получить задачу

curl --get "https://api.spicyapi.ai/api/v1/jobs/recordInfo" \
  --data-urlencode "taskId=$TASK_ID" \
  -H "Authorization: Bearer $SPICY_API_KEY"

Начните с интервала около 2 секунд и постепенно увеличивайте его. Прекратите опрос при конечном состоянии. После сбоя соединения используйте исходный taskId. Повторно создавать задачу можно только с исходным ключом идемпотентности и исходным телом запроса.

Или пусть вызов придёт сам

import { verifyWebhook } from "@spicyapi/sdk";

// express.raw keeps the bytes we signed; express.json never matches.
app.post("/hooks/spicy", express.raw({ type: "application/json" }), (req, res) => {
  const { payload } = verifyWebhook({
    rawBody: req.body,
    timestamp: req.header("X-Webhook-Timestamp"),
    signature: req.header("X-Webhook-Signature"),
    payloadVersion: Number(req.header("X-Webhook-Payload-Version")),
    secret: process.env.SPICY_WEBHOOK_SECRET,
  });
  res.status(200).end();
  void handleFinishedTask(payload);
});

Передайте callBackUrl при создании задачи — готовая запись придёт к вам POST-запросом, и никакого опроса не понадобится. В каждой доставке есть X-Webhook-Timestamp, X-Webhook-Signature и X-Webhook-Payload-Version. Подпись — это HMAC-SHA256 в base64 от taskId.timestamp.sha256(body), поэтому проверять её нужно по исходным байтам: если разобрать JSON и сериализовать заново, байты изменятся и проверка не пройдёт. Неудачные доставки повторяются, так что один и тот же taskId может прийти дважды — сделайте обработчик идемпотентным. Сначала ответьте 2xx, работу выполняйте после: медленный обработчик считается неудачной доставкой.

Прочитать результат

Обрабатывайте output только при state, равном succeeded. При ошибке проверьте errorCode, errorMessage и request_id. Стоимость и состояния в примерах не являются фактическим счётом.

Пример ответа после завершения

{
  "code": 200,
  "msg": "success",
  "request_id": "req_example_record",
  "data": {
    "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "model": "pixverse/v6/reference-to-video",
    "state": "succeeded",
    "output": {
      "assets": [
        {
          "key": "tasks/2026/08/28/job_01k3m8x9q2z4v7n5p6r8s0t1w3/3f7a1c9e5b2d48f0a6c1e3d5b7f9a1c3.mp4",
          "mime": "video/mp4",
          "url": "https://example.r2.cloudflarestorage.com/results/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4?X-Amz-Signature=SIGNATURE_FROM_RESPONSE",
          "expiresAt": "2026-08-28T12:20:08.000Z"
        }
      ]
    },
    "cost": "0.750000",
    "settled": true,
    "createdAt": "2026-08-28T12:00:00Z",
    "completedAt": "2026-08-28T12:00:30Z"
  }
}

Доступные файлы можно открыть или скачать по assets[].url без заголовка API Authorization. Подписанная ссылка действует до expiresAt. Чтобы обновить её, повторно запросите задачу в течение срока хранения файла. У ожидающих или недоступных файлов URL отсутствует. Не передавайте подписанные ссылки посторонним.

SDK и интеграции

Используйте SpicyAPI в приложении, терминале, ИИ-ассистенте или визуальном процессе. Выберите руководство по настройке.

SDKs

TypeScript · Python · Go · PHP · Java

CLI

Команды терминала и скрипты автоматизации.

MCP

Claude Code · Cursor · Codex

Agent Skill

Многоразовые инструкции для ИИ-ассистента.

n8n

Узлы сообщества для самостоятельного хостинга и импортируемые шаблоны HTTP Request для n8n Cloud.

ComfyUI

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

Другие интеграции

SillyTavern Telegram / Discord App proxy OpenAI SDK LangChain Vercel AI SDK

Посмотреть готовые рабочие процессы

Писать код выше вовсе не обязательно. Подключите сервер MCP один раз — и любой агент, который говорит на MCP (Claude Code, Codex, Cursor, Windsurf, VS Code, Gemini CLI, Cline, LibreChat), вызовет эту модель по имени. Либо запустите её из терминала одной командой.

Просто скажите это агенту

Возьми pixverse/v6/reference-to-video и сделай пятисекундный кадр: крыша в неоне на закате, медленный наезд. Сохрани в ./out/.

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

Подключается один раз

claude mcp add spicyapi -e SPICY_API_KEY=$SPICY_API_KEY \
  -- npx --yes --package=@spicyapi/mcp spicyapi-mcp
npx skills add spicyapi-ai/spicy-skill

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

Или одна команда в терминале

npx @spicyapi/cli tasks create --model pixverse/v6/reference-to-video \
  --input-json '{"prompt":"A slow aerial shot drifting over a misty pine forest at sunrise","elements":[{"name":"example","image_url":"https://example.com/reference.png"}],"resolution":"720p","aspect_ratio":"16:9","generate_audio":false,"duration_seconds":5}' \
  --wait

Входные данные взяты из схемы этого эндпоинта — той же, что и в примерах выше. --wait дождётся завершения задачи и выведет её, а --yes пропустит подтверждение в CI. Сначала задайте SPICY_API_KEY: один ключ работает и для API, и для CLI, и для сервера MCP.

Сколько хранятся результаты

npx @spicyapi/cli tasks create --model pixverse/v6/reference-to-video \
  --input-json '{…}' --retention 1h --wait

npx @spicyapi/cli tasks get $TASK_ID   # read back the retention that applied

Ключ --retention только сокращает срок — 30m, 1h, 7d или 0, чтобы удалить сразу после перехода задачи в конечное состояние. Реально действует наименьшее из трёх: ваш запрос, настройки аккаунта и предел платформы, — поэтому считайте его из записи задачи, а не исходите из того, что запрошенное число применилось. Запросить срок больше разрешённого аккаунтом нельзя: это ничего не изменит.

Использование в ComfyUI

Установите узлы SpicyAPI через ComfyUI Manager или командой ниже и найдите на холсте PixVerse V6 · Reference to Video. У узла те же параметры, что и на этой странице, а цена показывается до запуска.

cd ComfyUI/custom_nodes
git clone https://github.com/spicyapi-ai/comfyui-spicyapi

Готовые воркфлоу Руководство по установке Исходный код на GitHub

Встроенная панель читает ту же схему, что и эта страница, поэтому не может разойтись с API. Если содержимое должно индексироваться поиском по документации, возьмите JSON из /api/embed/models/ и отрисуйте его самостоятельно.

<iframe src="https://spicyapi.ai/embed/ru/models/pixverse-v6/api?model=pixverse%2Fv6%2Freference-to-video" width="100%" height="560" loading="lazy" title="Пример запроса" style="border:1px solid rgba(0,0,0,.12)"></iframe>

Открыть панель

Рабочая область

Отправить запрос

Аутентификация API

Входные параметры

Отследить задачу

Прочитать результат

SDK и интеграции

Использование в ComfyUI