Skip to main content

JS SDK

Call hy-image-v3.5-preview (the cloudbase provider) with @cloudbase/js-sdk, without going through a cloud function as a proxy.

caution

Image generation requires @cloudbase/js-sdk >= 3.11.0 and is only supported in server-side (Node.js) environments. Browsers cannot call it directly; use the Node SDK to create a cloud function as a proxy.

Prerequisites​

  • A CloudBase environment set up
  • @cloudbase/js-sdk 3.11.0 or higher
  • Image generation quota (such as the Mini Program growth plan)

Installation​

npm install @cloudbase/js-sdk

For on-demand imports, register the AI module:

import cloudbase from "@cloudbase/js-sdk/app";
import { registerAi } from "@cloudbase/js-sdk/ai";
registerAi(cloudbase);

Initialization​

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "your-env-id",
});

const ai = app.ai();

Basic Usage​

const imageModel = ai.createImageModel("cloudbase");

const res = await imageModel.generateImage({
  model: "hy-image-v3.5-preview",
  messages: [
    {
      role: "user",
      content: [{ type: "text", text: "A chubby orange cat napping on a windowsill, watercolor style, warm tones" }],
    },
  ],
});

// Final image, URL valid for 12 hours
const image = res.choices[0].delta.image;
console.log(image.url, image.width, image.height);

The cloudbase provider requires no generateImageSubUrlConfig; model routing is built into the SDK.

Common Parameters​

const res = await imageModel.generateImage({
  model: "hy-image-v3.5-preview",
  size: "4096x4096", // fixed size, 4K output
  seed: 42, // fixed seed; the same seed + prompt + size reproduces the result
  footnote: "Generated by Cloudbase", // bottom-right watermark, up to 16 characters
  session: "demo-session-001", // keep the same value across rounds
  messages: [
    { role: "user", content: [{ type: "text", text: "Cyberpunk city night scene, neon lights, rainy night" }] },
  ],
});

For the full parameter reference (size constraints, generate_max_pixels tiers, reference images, multi-round editing), see Hy-Image-3.5-preview.

Multi-Round Editing​

Append the assembled_history from the previous response to messages, then add the new user message:

const firstMessages = [
  { role: "user", content: [{ type: "text", text: "Draw a cat sitting on a windowsill" }] },
];

const firstRes = await imageModel.generateImage({
  model: "hy-image-v3.5-preview",
  session: "demo-session-001",
  messages: firstMessages,
});

const secondRes = await imageModel.generateImage({
  model: "hy-image-v3.5-preview",
  session: "demo-session-001",
  messages: [
    ...firstMessages,
    ...firstRes.assembled_history,
    { role: "user", content: [{ type: "text", text: "Change it to a ragdoll and move it next to a fireplace" }] },
  ],
});

Save to Cloud Storage​

Generated image URLs expire after 12 hours. Download and persist them to cloud storage:

import https from "https";
import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({ env: process.env.ENV_ID });
const ai = app.ai();

async function generateAndSave(prompt) {
  const imageModel = ai.createImageModel("cloudbase");

  const res = await imageModel.generateImage({
    model: "hy-image-v3.5-preview",
    messages: [{ role: "user", content: [{ type: "text", text: prompt }] }],
  });

  const imageUrl = res.choices[0].delta.image.url;
  const imageBuffer = await downloadImage(imageUrl);

  const uploadRes = await app.uploadFile({
    cloudPath: `ai-images/${Date.now()}.jpg`,
    fileContent: imageBuffer,
  });

  return uploadRes.fileID;
}

function downloadImage(url) {
  return new Promise((resolve, reject) => {
    https.get(url, (response) => {
      const chunks = [];
      response.on("data", (chunk) => chunks.push(chunk));
      response.on("end", () => resolve(Buffer.concat(chunks)));
      response.on("error", reject);
    });
  });
}
Timeout

Image generation takes a while (longer for 4K). Set the cloud function timeout to 900 seconds.