Skip to main content

JS SDK

Call the Hunyuan image generation model directly via @cloudbase/js-sdk, without going through a cloud function as a proxy.

caution

Image generation requires @cloudbase/js-sdk v3.17.0 or higher and is only supported in server-side (Node.js) environments. Browser-side environments do not support direct image generation calls. To generate images from a web page, use the Node SDK to create a cloud function as a server-side endpoint, then call it from the web page.

Prerequisites​

  • A CloudBase environment set up
  • @cloudbase/js-sdk v3.17.0 or higher
  • Image generation resources granted by the Mini Program Growth Plan

Installation​

npm install @cloudbase/js-sdk

For tree-shaking imports, register the AI module separately:

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

Usage Example​

Basic Image Generation​

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

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

const ai = app.ai();

const imageModel = ai.createImageModel("hunyuan-image");
imageModel.generateImageSubUrlConfig["hunyuan-image"]["HY-Image-3.0-Plus-4090-Tob-v1.0"] =
  "images/ar/generations";

const res = await imageModel.generateImage({
  model: "HY-Image-3.0-Plus-4090-Tob-v1.0",
  prompt: "A chubby orange cat napping on a windowsill, watercolor style, warm tones",
  size: "1024x1024",
  revise: { value: true },
});

console.log(res.data[0].url); // Image URL, valid for 24 hours
console.log(res.data[0].revised_prompt); // Revised prompt

Custom Parameters​

Customize image size, prompt revision, and thinking mode:

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

const imageModel = ai.createImageModel("hunyuan-image");
imageModel.generateImageSubUrlConfig["hunyuan-image"]["HY-Image-3.0-Plus-4090-Tob-v1.0"] =
  "images/ar/generations";

const res = await imageModel.generateImage({
  model: "HY-Image-3.0-Plus-4090-Tob-v1.0",
  prompt: "Cyberpunk style future city nightscape, neon lights, rainy night",
  size: "768x1024", // Portrait orientation
  seed: 42, // Fixed seed for reproducibility
  footnote: "Generated by Cloudbase", // Custom watermark
  revise: { value: true }, // Enable prompt revision
});

Parameter Reference​

ImageModel.generateImage​

generateImageSubUrlConfig​

The sub-path mapping must be configured before calling generateImage:

imageModel.generateImageSubUrlConfig["hunyuan-image"]["HY-Image-3.0-Plus-4090-Tob-v1.0"] =
  "images/ar/generations";

Input Parameters​

interface HunyuanARGenerateImageInput {
  model: "HY-Image-3.0-Plus-4090-Tob-v1.0";
  prompt: string; // Text prompt, up to 8192 characters
  size?: string; // Image size, format "${width}x${height}", default "1024x1024"
  seed?: number; // Generation seed, range [1, 4294967295]
  footnote?: string; // Custom watermark, up to 16 characters
  revise?: { value: boolean }; // Enable prompt revision, enabled by default
}

Return Value​

interface HunyuanARGenerateImageOutput {
  id: string;
  created: number;
  data: Array<{
    url: string; // Image URL, valid for 24 hours
    revised_prompt?: string; // Revised prompt text
  }>;
}

Full Example​

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

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

const ai = app.ai();

async function generateImage(prompt, options = {}) {
  const imageModel = ai.createImageModel("hunyuan-image");
  imageModel.generateImageSubUrlConfig["hunyuan-image"]["HY-Image-3.0-Plus-4090-Tob-v1.0"] =
    "images/ar/generations";

  const res = await imageModel.generateImage({
    model: "HY-Image-3.0-Plus-4090-Tob-v1.0",
    prompt,
    size: options.size || "1024x1024",
    seed: options.seed,
    footnote: options.footnote,
    revise: { value: options.revise !== false },
  });

  return {
    url: res.data[0].url,
    revisedPrompt: res.data[0].revised_prompt,
  };
}

// Usage
const { url, revisedPrompt } = await generateImage(
  "A traditional Chinese ink wash landscape painting, distant mountains and near water, serene atmosphere",
  { size: "1024x768" }
);
console.log("Image URL:", url);
console.log("Revised prompt:", revisedPrompt);

Save to Cloud Storage​

Generated image URLs expire after 24 hours. Save the image to cloud storage for permanent 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) {
  // 1. Generate image
  const imageModel = ai.createImageModel("hunyuan-image");
  imageModel.generateImageSubUrlConfig["hunyuan-image"]["HY-Image-3.0-Plus-4090-Tob-v1.0"] =
    "images/ar/generations";

  const res = await imageModel.generateImage({
    model: "HY-Image-3.0-Plus-4090-Tob-v1.0",
    prompt,
    revise: { value: true },
  });

  // 2. Download image
  const imageBuffer = await downloadImage(res.data[0].url);

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

  return {
    fileID: uploadRes.fileID,
    revisedPrompt: res.data[0].revised_prompt,
  };
}

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 is time-consuming (revise mode adds ~30 seconds, thinking mode adds up to 60 seconds). When calling in a cloud function, set the timeout to 900 seconds.