Быстрый старт с API PixMind: генерация изображений в Node.js

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

В этом руководстве мы создадим небольшой серверный клиент на Node.js для такого сценария. В нём есть отдельные команды submit и resume: первая создаёт задачу, а вторая только проверяет уже существующую. Начните со списка ID моделей, поддерживаемых API, а не с названия модели, скопированного с баннера на главной странице.

Руководство посвящено генерации изображений по текстовому описанию. Загрузка референсных файлов, реализация браузерного интерфейса и оценка качества моделей в него не входят. Проверка включает 29 локальных тестов с имитацией ответов и одну контролируемую задачу генерации изображения в рабочей среде, выполненную 4 сентября 2026 года. Эта задача вернула одно изображение; за неё зафиксировано списание 120 баллов API. Это единичная проверка интеграции на конкретную дату, а не тест скорости, универсальная цена или гарантия доступности для другого аккаунта.

На обложке показан снимок экрана каталога моделей от 4 сентября 2026 года. Рассматривайте его как иллюстрацию на указанную дату, а не как актуальное ценовое предложение или гарантию доступности.

Главное

• Храните ключ API на сервере, не включайте его в браузерные сборки и публичные репозитории.
• Для задачи генерации изображения считайте числовой data.taskId из ответа о принятии запроса и сохраните его для последующих запросов.
• Выполняйте опрос сохранённой задачи до статуса ready или failed. Читайте URL изображений из data.images только после успешного завершения.
• Тайм-аут клиента не доказывает, что удалённая задача завершилась ошибкой или была отменена. Если ID задачи известен, возобновите запросы её состояния; не повторяйте запрос на создание вслепую.

В этом руководстве

• Перед началом
• Выбор модели и настройка ключа API
• Отправка запроса с помощью cURL
• Опрос состояния задачи и получение URL изображений
• Полный пример на Node.js
• Обработка ошибок
• Отличия для видео и чата
• Проверка интеграции

Перед началом

Используйте закрытое терминальное или серверное окружение с Node.js, ключом API и аккаунтом с настроенной оплатой API. Пример использует встроенный fetch и модули JavaScript; установка сторонних пакетов не требуется. В документации глобальных API Node.js описаны fetch и AbortSignal.timeout, с помощью которых клиент ограничивает длительность отдельного запроса. Локальная проверка проводилась в Windows с Node.js v22.22.1; это описание тестового окружения, а не утверждение, что все остальные версии тоже проверены.

Для работы с примером нужно уметь редактировать файлы, задавать переменные окружения и читать JSON. Прежде чем продолжить, проверьте установленную версию среды выполнения:

node --version

Команда должна вывести установленную версию. Она не обращается к API генерации. Сохраните полный код клиента из раздела ниже в файл examples/pixmind-image.mjs внутри рабочей папки, а затем запускайте команды из этой папки.

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

Если вам нужно просто создать изображение в интерактивном режиме, этот процесс описан в руководстве по Image Agent. Представленный здесь клиент предназначен для приложения, которое явно передаёт ID модели и самостоятельно обрабатывает ответ.

Выбор модели и настройка ключа API

Используйте ID модели, поддерживаемой API, и параметры, которые поддерживает эта модель. В примере выбрана nano-banana-pro с параметрами aspectRatio: "1:1" и resolution: "1K", как в запросе на генерацию изображения из руководства по быстрому старту с API. Запрос GET /models с аутентификацией и проверка в рабочей среде подтвердили эту комбинацию для тестового аккаунта 4 сентября 2026 года. Перед реальным запуском повторно проверьте доступность модели и поддержку параметров для своего аккаунта. Замена только строки с названием модели не гарантирует, что остальные поля запроса останутся допустимыми.

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

Для PowerShell:

$env:PIXMIND_API_KEY = "REPLACE_WITH_YOUR_PRIVATE_API_KEY"
$env:PIXMIND_MODEL = "nano-banana-pro"
$env:PIXMIND_PROMPT = "A ceramic coffee cup on a plain studio background, soft side lighting, no text"

Для Bash:

export PIXMIND_API_KEY="REPLACE_WITH_YOUR_PRIVATE_API_KEY"
export PIXMIND_MODEL="nano-banana-pro"
export PIXMIND_PROMPT="A ceramic coffee cup on a plain studio background, soft side lighting, no text"

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

Базовый URL в этом руководстве:

https://aihub-admin.aimix.pro/api-platform/v1

Добавляйте к нему /generations или /tasks/{taskId}. Не добавляйте второй /v1. Список моделей можно получить через GET /models; при этом перед выбором параметров удобнее изучить возможности конкретных моделей в каталоге.

Отправка первого запроса на генерацию изображения с помощью cURL

Запрос cURL служит альтернативой команде submit клиента Node.js, а не подготовительным шагом, который обязательно нужно выполнить первым. Оба варианта отправляют запрос на генерацию. Запуск обоих может создать две платные задачи. Если вы отправили запрос через cURL, затем используйте команду resume клиента Node.js с полученным ID задачи.

В примере используется синтаксис Bash. В PowerShell воспользуйтесь клиентом Node.js ниже, а не вставляйте в терминал команды с переносами строк в формате Bash.

curl --connect-timeout 10 --max-time 30 \
  --request POST \
  'https://aihub-admin.aimix.pro/api-platform/v1/generations' \
  --header "Authorization: Bearer $PIXMIND_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "nano-banana-pro",
    "type": "image",
    "prompt": "A ceramic coffee cup on a plain studio background, soft side lighting, no text",
    "aspectRatio": "1:1",
    "resolution": "1K"
  }'

Промпт и параметры в теле этого запроса cURL заданы непосредственно в коде. Изменение PIXMIND_PROMPT не меняет этот JSON: данную переменную окружения читает клиент Node.js. Это различие помогает отделить содержимое запроса, который вы собираетесь отправить, от настроек окружающей его оболочки.

Ниже приведён сокращённый иллюстративный ответ о принятии запроса. ID в нём является заполнителем, а не ID из проверки в рабочей среде; запрашивать задачу 12345 не следует.

{
  "code": 1000,
  "message": "success",
  "data": {
    "id": "img_12345",
    "taskId": 12345
  }
}

В проверенных ответах API для медиа в рабочей среде успешные данные были заключены в объект с полями code, message, data и timestamp; в иллюстрации метка времени и другие поля опущены. Для этого сценария нужны и успешный ответ HTTP, и корректный ответ на уровне приложения. Читайте data.taskId, а не data.id: последнее поле может содержать строку с префиксом, например img_12345, тогда как путь запроса состояния задачи использует числовой ID.

Сразу сохраните этот числовой ID. Если запрос завершился по тайм-ауту до его получения, остановитесь и выясните результат отправки по записям задач в аккаунте или через поддержку. Повторная отправка POST не является безопасной заменой выяснению того, что произошло.

Опрос состояния задачи и получение URL изображений

Запрашивайте состояние существующей задачи, пока она не перейдёт в конечное состояние. В документации по асинхронным задачам описаны pending, processing, ready и failed. Только последние два состояния завершают этот цикл опроса.

Submit once
    |
Save numeric taskId
    |
GET /tasks/{taskId} <--- wait, then query again
    |                            ^
    +--- pending / processing ---+
    |
    +--- ready  ---> read images, stop
    |
    +--- failed ---> report failure, stop

Для ручного запроса в Bash замените ID-заполнитель своим ID:

TASK_ID="REPLACE_WITH_YOUR_NUMERIC_TASK_ID"
curl --connect-timeout 10 --max-time 30 \
  "https://aihub-admin.aimix.pro/api-platform/v1/tasks/$TASK_ID" \
  --header "Authorization: Bearer $PIXMIND_API_KEY"

В текущем контракте ответа API для медиа нужные вам поля выполняют разные функции:

Ответ ready без пригодных для использования URL изображений не является успешным результатом генерации для вашего приложения. Сообщите об этом несоответствии вместе с ID задачи, чтобы можно было разобраться в причине. Не подставляйте URL из примера и не сообщайте, что изображение было скачано.

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

Запуск полного примера на Node.js

Используйте submit для одной новой задачи, а resume для существующей. При запуске без аргументов скрипт выводит справку по использованию и не обращается к API. Такое поведение по умолчанию не даёт обычному перезапуску или беглому знакомству с интерфейсом командной строки создать новую задачу.

Сохраните полный исходный код ниже в файл examples/pixmind-image.mjs:

import { pathToFileURL } from 'node:url';

const BASE_URL = 'https://aihub-admin.aimix.pro/api-platform/v1';
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));

export class ApiError extends Error {
  constructor(message, { status = 0, transient = false, retryAfterMs = 0 } = {}) {
    super(message);
    Object.assign(this, { status, transient, retryAfterMs });
  }
}

export function parseTaskId(value) {
  if (!/^\d+$/.test(String(value))) throw new Error('Use a numeric taskId, not img_...');
  const id = Number(value);
  if (!Number.isSafeInteger(id) || id <= 0) throw new Error('Invalid taskId');
  return id;
}

export function retryAfter(value, now) {
  if (!value) return 0;
  if (/^\d+(\.\d+)?$/.test(value)) return Number(value) * 1000;
  const date = Date.parse(value);
  return Number.isFinite(date) ? Math.max(0, date - now) : 0;
}

export function createClient({
  apiKey,
  fetchImpl = fetch,
  now = Date.now,
  wait = sleep,
  random = Math.random,
  requestTimeoutMs = 30_000,
  pollTimeoutMs = 300_000,
  maxConsecutiveErrors = 5,
} = {}) {
  if (typeof apiKey !== 'string' || !apiKey.trim()) throw new Error('Set PIXMIND_API_KEY');

  async function request(path, method, payload, timeoutMs = requestTimeoutMs) {
    let response;
    let body;
    try {
      response = await fetchImpl(`${BASE_URL}${path}`, {
        method,
        redirect: 'error',
        headers: {
          Authorization: `Bearer ${apiKey}`,
          ...(payload ? { 'Content-Type': 'application/json' } : {}),
        },
        ...(payload ? { body: JSON.stringify(payload) } : {}),
        signal: AbortSignal.timeout(Math.max(1, Math.ceil(timeoutMs))),
      });
      // Read the body inside the timeout/network error boundary as well.
      body = await response.text();
    } catch {
      throw new ApiError('Network error or request timeout', { transient: true });
    }
    let envelope;
    try { envelope = JSON.parse(body); } catch { /* handle below */ }
    const transient = response.status === 429 || response.status >= 500;
    if (!response.ok) {
      // Do not echo arbitrary server bodies, prompts, credentials, or output URLs.
      throw new ApiError(`HTTP ${response.status}; inspect the account and request`, {
        status: response.status,
        transient,
        retryAfterMs: retryAfter(response.headers.get('retry-after'), now()),
      });
    }
    if (!envelope || typeof envelope !== 'object') {
      throw new ApiError('Expected a JSON API response');
    }
    if (envelope.code !== 1000 || !envelope.data) {
      throw new ApiError('API returned an unsuccessful or incomplete envelope');
    }
    return envelope.data;
  }

  async function submit({ model = 'nano-banana-pro', prompt } = {}) {
    if (typeof model !== 'string' || !model.trim()) throw new Error('A model is required');
    if (typeof prompt !== 'string' || !prompt.trim()) throw new Error('A prompt is required');
    try {
      const data = await request('/generations', 'POST', {
        model, type: 'image', prompt, aspectRatio: '1:1', resolution: '1K',
      });
      // The public media contract returns a number, not the prefixed display ID.
      if (typeof data.taskId !== 'number') throw new Error('Missing numeric taskId');
      return parseTaskId(data.taskId);
    } catch (error) {
      // A timeout or malformed response does not prove that creation failed.
      throw new Error(`Submission not confirmed: ${error.message}. No automatic retry was made. Check task records before submitting again.`);
    }
  }

  async function poll(taskId) {
    const id = parseTaskId(taskId);
    const deadline = now() + pollTimeoutMs;
    let attempts = 0;
    let errors = 0;
    const timedOut = () => new Error(`Stopped waiting for task ${id}; it may still be running. Resume this ID later.`);
    while (now() < deadline) {
      let retryFloor = 0;
      let task;
      try {
        task = await request(`/tasks/${id}`, 'GET', undefined,
          Math.min(requestTimeoutMs, deadline - now()));
        errors = 0;
      } catch (error) {
        if (now() >= deadline) throw timedOut();
        if (!(error instanceof ApiError) || !error.transient) throw error;
        errors += 1;
        if (errors >= maxConsecutiveErrors) {
          throw new Error(`Stopped after ${errors} consecutive query errors for task ${id}; resume this ID later.`);
        }
        retryFloor = error.retryAfterMs;
      }
      if (now() >= deadline) throw timedOut();
      if (task) {
        if (task.taskId !== id) throw new Error('Task response ID does not match the requested task');
        if (task.status === 'failed') throw new Error(`Task ${id} failed; inspect its record before creating another task.`);
        if (task.status === 'ready') {
          if (!Array.isArray(task.images) || task.images.length === 0 ||
              !task.images.every(url => {
                try { return ['https:', 'http:'].includes(new URL(url).protocol); }
                catch { return false; }
              })) throw new Error(`Task ${id} is ready but has no valid image URLs`);
          return task.images;
        }
        if (!['pending', 'processing'].includes(task.status)) {
          throw new Error(`Task ${id} returned an unrecognized status; inspect its record.`);
        }
      }
      // Client policy, not a PixMind latency guarantee or server-side retry feature.
      const ceiling = Math.min(10_000, 1_000 * 2 ** Math.min(attempts++, 4));
      const delay = Math.max(retryFloor, ceiling * (0.5 + 0.5 * random()));
      const remaining = deadline - now();
      if (delay >= remaining) {
        // Never poll earlier than Retry-After just to fit the local deadline.
        await wait(Math.max(0, remaining));
        throw timedOut();
      }
      await wait(delay);
    }
    throw timedOut();
  }

  return { submit, poll };
}

export async function main(args = process.argv.slice(2), env = process.env, deps = {}) {
  const log = deps.log ?? console.log;
  const [mode, rawId] = args;
  if (!mode) {
    log('Usage: node examples/pixmind-image.mjs submit | resume TASK_ID');
    return;
  }
  if (!((mode === 'submit' && args.length === 1) || (mode === 'resume' && args.length === 2))) {
    throw new Error('Use submit, or resume followed by a numeric taskId');
  }
  const resumeId = mode === 'resume' ? parseTaskId(rawId) : undefined;
  const client = createClient({ ...deps, apiKey: env.PIXMIND_API_KEY });
  const id = resumeId ?? await client.submit({
    model: env.PIXMIND_MODEL || 'nano-banana-pro',
    prompt: env.PIXMIND_PROMPT || 'A studio photograph of an unbranded ceramic coffee cup on a plain background',
  });
  // Save this line in your application record before relying on the polling process.
  log(`TASK_ID=${id}`);
  log(`Resume without a new generation: node examples/pixmind-image.mjs resume ${id}`);
  const images = await client.poll(id);
  log(JSON.stringify({ taskId: id, images }, null, 2));
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  main().catch(error => { console.error(error.message); process.exitCode = 1; });
}

Сначала изучите интерфейс команд, ничего не отправляя:

node examples/pixmind-image.mjs

Проверив ключ, параметры модели и ожидаемое списание, создайте одну задачу:

node examples/pixmind-image.mjs submit

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

Чтобы продолжить запросы состояния задачи, замените 12345 сохранённым значением:

node examples/pixmind-image.mjs resume 12345

Эта команда выполняет только GET-запросы к задаче. Она не читает новый промпт и не создаёт ещё одно изображение. При успешном завершении вы должны получить URL результатов своей задачи; выдуманные результаты из рабочей среды в качестве эталона здесь не приводятся.

В примере задан лимит 30 секунд на каждый HTTP-запрос и общий предельный срок опроса в пять минут. Для повторных GET-запросов используется экспоненциальное увеличение задержки со случайным разбросом, локальным ограничением задержки в 10 секунд и корректным заголовком ответа Retry-After, когда он применим. Более длительное ожидание, заданное сервером, имеет приоритет; если оно не укладывается в локальный предельный срок, клиент останавливается, не отправляя запрос раньше указанного времени. Пятая временная ошибка GET подряд завершает попытку, то есть для такой последовательности ошибок допустимы четыре повтора. Эти значения являются настройками клиента, а не соглашением об уровне обслуживания или обещанием, что каждое изображение будет готово за пять минут.

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

Обработка ошибок без повторного запуска платной генерации

Неопределённый результат создания задачи и неудачный запрос её состояния требуют разного подхода. GET-запрос состояния задачи можно повторить, не создавая ещё одну генерацию. POST-запрос создания, ответ на который потерялся, уже мог запустить работу, поэтому пример никогда не отправляет его повторно автоматически.

Не предполагайте, что все ошибки возвращаются в одной структуре ответа. При проверке в рабочей среде 4 сентября запрос GET /models без аутентификации вернул HTTP 401 только с полями code и message; успешные ответы API для медиа с аутентификацией также содержали data и timestamp. Поэтому это руководство не обещает наличие requestId, флага retryable или поля с ценой в каждом ответе. Остальные случаи ошибок в таблице выше описывают поведение клиента, а не утверждают, что каждый из них был воспроизведён в рабочей среде. Сохраняйте статус HTTP и очищенное от чувствительных данных сообщение приложения, если оно присутствует; считайте некорректное тело ответа ошибкой, не допуская аварийного завершения внутри JSON.parse.

Тайм-аут опроса означает, что клиент перестал ждать, а не что удалённая задача отменена. Сохраните ID и возобновите опрос позже. Незнакомый статус тоже не свидетельствует об успехе: этот клиент останавливается и сообщает о нём для дальнейшего разбора. Никогда не считайте задачу «завершённой» только потому, что её значение статуса отсутствует в операторе switch.

Для устранения неполадок сохраняйте ID задачи, ID модели, операцию, статус HTTP и приблизительное время. Не записывайте заголовки авторизации и полные тела запросов с конфиденциальными промптами. Перед передачей диагностических тел ответов или URL результатов проверьте, не содержат ли они чувствительные сведения.

Адаптация схемы для видео и чата

Для видео можно использовать ту же схему отправки и опроса, но ему нужны собственная проверка запроса и обработка результата. Уточните требования выбранной видеомодели к входным медиафайлам, длительности, разрешению и параметрам звука, а не переносите поля из запроса изображения на основании предположений. Готовое видео использует data.videoUrl, а не data.images.

В руководстве по Video Agent описан интерактивный творческий процесс. Он поможет определить нужный кадр до автоматизации генерации, но наличие функции в Agent не доказывает существования одноимённого параметра API.

Чат представляет собой отдельный путь интеграции. Документированный маршрут /chat/completions совместим с OpenAI и возвращает ответ чата либо поток, если запрошен потоковый режим. Не передавайте этот ответ парсеру data.taskId из клиента изображений. Общий базовый URL не означает одинаковой структуры ответов у всех эндпоинтов.

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

Проверка интеграции и выбор следующего шага

Локальные тесты с имитацией ответов проверяют поведение клиента, не расходуя баланс API. Прилагаемый набор успешно прошёл 29 тестов в указанном окружении Windows и Node.js, включая создание с единственным POST, возобновление только через GET, некорректные ответы, конечное состояние ошибки, предельные сроки и ограничения повторов. Сохраните прилагаемый файл тестов рядом с исходным кодом клиента, затем запустите набор из папки руководства:

node --test examples/pixmind-image.test.mjs

Тесты с имитацией ответов не подтверждают доступность в рабочей среде или фактические списания. Для отдельной контролируемой проверки 4 сентября 2026 года использовался тот же клиент; зафиксированы следующие условия и результаты:

Для проверки использовались один существующий ключ API проекта и промпт без чувствительных данных; референсы не загружались, автоматических повторов создания не было. Запись о списании сопоставили с ID задачи, а не вывели из показаний баланса Studio. В рабочей среде были проверены только эта конфигурация и успешный сценарий получения изображения; видео, чат, списания при ошибках, возвраты и надёжность при повторных запусках не проверялись. Перед своей отправкой заново уточните цену, не принимая это историческое списание за постоянно действующее предложение.

Перед подключением примера к реальному пользовательскому процессу проверьте следующее:

• Ключ остаётся на сервере и отсутствует в клиентских сборках, снимках экрана и публичных журналах.
• Выбранная модель и каждый параметр поддерживаются текущим предложением API.
• После принятия запроса у вас остаётся числовой ID задачи, доступный для возобновления работы.
• resume не выполняет POST-запросов создания, в том числе после временных ошибок запросов состояния.
• Ошибка задачи, пустой результат и локальный тайм-аут дают разные диагностические результаты.
• Потеря ответа на создание не вызывает автоматическую повторную отправку.

Для собственной контролируемой проверки в рабочей среде зафиксируйте аккаунт, модель, согласованные пределы расходов, очищенный от чувствительных данных запрос, ID задачи, ответ с конечным состоянием и фактическую запись о списании. Проверьте само изображение отдельно от проверки наличия его URL. Не запускайте повторные «смоук-тесты», не учитывая, что каждая новая отправка может запустить платную работу.

Когда будете готовы, создайте ключ API и выберите один способ отправки. Сначала выстройте работу вокруг сохранённой задачи, а уже потом добавляйте очереди, загрузки файлов или пакетную обработку. Если следующим шагом нужно включить сгенерированные материалы в творческий процесс с проверкой человеком, сценарий создания рекламы товара в Canvas показывает отдельный пример под управлением человека; это не обещание, что проекты Canvas можно выполнять через данный API.

Редакционная ответственность: PixMind Editorial Team является организационным автором этого руководства. Его доказательная база включает официальную документацию, реализацию медиаконтроллера проекта, 29 локальных тестов с имитацией ответов и единственную проверку в рабочей среде, описанную выше; все материалы проверены 4 сентября 2026 года. Очищенные от чувствительных данных записи о задаче и списании сохранены для редакционной проверки. Здесь не заявляются квалификация конкретного инженера, результаты сравнительной оценки качества моделей или показатели теста производительности.

Wan 3.0 Video: полное руководство по исходным данным, аудио, ценам и API