Hy-Image-3.5-preview

hy-image-v3.5-preview submits image generation requests via the Chat/Messages protocol and returns results synchronously. It supports multimodal input (text + reference images), multi-round editing, and output up to 4096x4096 (4K).

Prerequisites

@cloudbase/js-sdk 3.11.0 or later
An enabled CloudBase environment with image generation quota (such as the Mini Program growth plan)
Called only through the CloudBase SDK. Unlike the legacy hunyuan-image channel, no generateImageSubUrlConfig setup is required

Usage Examples

Basic Text-to-Image

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

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

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

const res = await imageModel.generateImage({
  model: "hy-image-v3.5-preview",
  messages: [
    {
      role: "user",
      content: [{ type: "text", text: "A golden retriever running on a beach, warm evening light" }],
    },
  ],
});

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

4K Output

const res = await imageModel.generateImage({
  model: "hy-image-v3.5-preview",
  size: "4096x4096", // width/height in [256, 8192], area up to 4096x4096
  messages: [
    { role: "user", content: [{ type: "text", text: "A poster-quality city night scene" }] },
  ],
});

Reference Image

Mix text and images in content. Images support public URLs or Base64 (data:image/...;base64,...):

const res = await imageModel.generateImage({
  model: "hy-image-v3.5-preview",
  session: "demo-session-001", // keep the same session across rounds
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Draw a cat in the style of this image" },
        { type: "image_url", image_url: { url: "https://your-domain.com/dog.png" } },
      ],
    },
  ],
});

Multi-Round Editing

The next round's messages = previous round's messages + the assembled_history from the previous response + the new user message. assembled_history is assembled by the server and can be passed through directly:

// Round 1
const firstMessages = [
  {
    role: "user",
    content: [
      { type: "text", text: "Draw a cat in the style of this image" },
      { type: "image_url", image_url: { url: "https://your-domain.com/dog.png" } },
    ],
  },
];
const firstRes = await imageModel.generateImage({
  model: "hy-image-v3.5-preview",
  session: "demo-session-001",
  messages: firstMessages,
});

// Round 2: feed assembled_history back and continue editing
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 the cat to a ragdoll, move it next to a fireplace" }] },
  ],
});

Input Parameters

Parameter	Type	Required	Description
`model`	string	Yes	Fixed to `hy-image-v3.5-preview`; the SDK throws immediately for other values
`messages`	`Array<object>`	Yes	Conversation content ordered from oldest to newest; the server takes the last `role=user` message as the current instruction
`size`	string	No	Output size in `${width}x${height}` format. Width/height in [256, 8192], area up to 4096x4096. When set, output is forced to this size
`seed`	integer	No	Generation seed in [0, 2^63-1]; 0 or omitted means random. Fix seed + prompt + size to reproduce results
`generate_max_pixels`	integer	No	Target area tier, effective only when `size` is not set. Options: `1048576` (1K), `2359296` (1.5K, default), `4194304` (2K)
`resize_max_pixels`	integer	No	Area limit for input reference images, default `1048576`; larger images are scaled down before entering the model
`session`	string	No	Session ID; keep the same value across rounds so requests land on the same inference instance
`footnote`	string	No	Custom watermark, up to 16 characters, rendered at the bottom-right corner
`use_search_tool`	`{ value: boolean }`	No	External search enhancement switch, off by default

messages Element

Parameter	Type	Required	Description
`role`	string	Yes	`user` / `assistant` / `tool`; `tool` appears only when feeding back the previous round's result
`content`	`Array<object>`	No	Content of the round, see the table below. Can be omitted when `assistant` only triggers tool calls
`reasoning`	string	No	Used only when feeding back `assistant` messages; pass through the reasoning text from the previous response
`tool_calls`	`Array<object>`	No	Used only when feeding back `assistant` messages; standard OpenAI tool_call structure
`tool_call_id`	string	No	Used only when feeding back `role=tool`; must match `tool_calls[i].id`

content Element

Parameter	Type	Required	Description
`type`	string	Yes	`text` or `image_url`
`text`	string	No	Text content when `type=text`
`image_url`	`{ url: string }`	No	Image when `type=image_url`; supports public URLs or Base64. Up to 20MB per image, at most 20 images

Size and Area Combinations

Combination	Result
`size` only	Forced to the exact dimensions; use this for 4K
`size` + `generate_max_pixels`	Balances the ratio of `size` and the area tier for the best model output
`generate_max_pixels` only	1:1 ratio by default, area snapped to 1K / 1.5K / 2K
Neither	Model decides based on prompt semantics (default 1.5K tier)

⚠️ The highest generate_max_pixels tier is 2K; 4K output must be specified via size.

Response

interface CloudbaseGenerateImageOutput {
  id: string; // request trace ID
  object: string; // fixed "image.chat.completion.chunk"
  created: number; // Unix timestamp in seconds
  model: string; // upstream internal version, not recommended for branching
  round: number; // LLM round, starting from 0
  choices: Array<{
    index: number;
    delta: {
      type?: string;
      image?: {
        url: string; // final image URL, valid for 12 hours
        width: number;
        height: number;
        source: string;
        tool_call_id: string;
      };
    };
    finish_reason?: string | null; // usually null on success; check delta.image instead
  }>;
  usage?: { total_tokens: number };
  tokenhub_usage?: { total_tokens: number };
  request_id?: string;
  assembled_history?: Array<object>; // messages to feed back for the next round
  error?: { type: string; code: string; message: string; request_id?: string };
}

Read the final image from choices[0].delta.image.url; the role=tool image URL inside assembled_history is an intermediate artifact used only for the next round.

⚠️ All image URLs are temporary and valid for 12 hours. Download and persist them to cloud storage in time.

Error Codes

HTTP Status	Description	Suggestion
400	Invalid request format	Check field types and values (size constraints, messages structure)
401	Authentication failed	Check the environment and authentication method
422	Content moderation rejected	Adjust the prompt or business policy
429	Concurrency limit exceeded	Retry with backoff and control concurrency
500	Internal server error	Retry; if it persists, contact support with the `request_id`

Timeout

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

Image Generation Overview — model capability overview
JS SDK Usage — JS SDK requirements and initialization
Text-to-Image (legacy model) — HY-Image-3.0 usage

Prerequisites​

Usage Examples​

Basic Text-to-Image​

4K Output​

Reference Image​

Multi-Round Editing​

Input Parameters​

messages Element​

content Element​

Size and Area Combinations​

Response​

Error Codes​

Related Documentation​