Hy Image 3.5 API Setup: 12 Steps, $0.024/Image [2026]

Tencent shipped a new image-generation model on September 22, 2026, and most developers outside China have not touched it yet. Hy Image 3.5 Preview (the model Tencent’s own engineers call 混元图像3.5预览版, or Hunyuan Image 3.5 internationally) landed on Tencent Cloud’s TokenHub console with a price tag that undercuts nearly every Western rival: $0.024 per image on the international API, versus $0.045 to $0.211 for a single GPT Image 2.5 output depending on quality tier. This tutorial walks through the full setup, from creating a Tencent Cloud account to shipping a working CLI tool that calls the Hy Image 3.5 API, handles multi-turn edits, and logs cost per request.

You’ll need roughly 90 minutes for the full walkthrough, including account verification (Tencent Cloud can take 10-15 minutes to activate billing on a new account). By the end you’ll have a script that generates images from text, edits them conversationally with reference photos, and falls back to a second provider when Hy Image 3.5 rate-limits you. If you’ve already set up the Qwen Image 3.0 API or the GPT Image 2.5 API, the pattern here will feel familiar, though Tencent’s authentication flow and billing console have a few quirks worth flagging up front.

·

Google · Preferred Sources

Don't miss new tech stories on Google

Add Tech Insider once in the Google app and our stories appear in your news suggestions.

Add Now

What Hy Image 3.5 Preview actually is

Hy Image 3.5 Preview is Tencent Hunyuan’s newest image-generation model, released September 22, 2026, as a hosted preview rather than a downloadable checkpoint. Tencent Cloud lists it under two identifiers depending on which API surface you use: hy-image-v3.5-preview in the TokenHub console, and Hy-Image-3.5-Preview in the newer Chat/Messages protocol documentation. Both point to the same underlying model. It supports text-to-image generation, image-to-image editing with up to five reference photos per request, and multi-turn conversational editing that carries context across a session.

Tencent’s own comparison data, drawn from a blind evaluation involving hundreds of professional designers using a “Good/Same/Bad” (GSB) scoring method, claims roughly a 30% quality improvement over the prior Hy Image 3.0 generation. In that same internal test, Hy Image 3.5 scored about even with ByteDance’s Seedream 5.0 Pro and slightly ahead of Google’s Nano Banana Pro and Alibaba’s Qwen Image 3.0 Pro. Treat that figure the way you’d treat any vendor-run benchmark: it’s a real data point, but it’s not an independently reproducible score like an LMArena Elo rating or a public GenEval result, and Tencent hasn’t published the prompts or sample sizes behind it.

The model is already wired into several of Tencent’s own consumer products, including Yuanbao, WorkRally, OnSolo, Miora, WorkBuddy, and the ima app. For developers, the relevant entry point is Tencent Cloud’s TokenHub, the same console Tencent uses to serve its Hunyuan LLM family. As of this writing there’s no Hugging Face repository, no published parameter count, and no open license for Hy Image 3.5. If you were hoping to run it locally through ComfyUI or diffusers the way you can with FLUX.2 Klein, that’s not an option yet. This is an API-only model, at least for now.

Understanding the GSB testing methodology Tencent used

GSB stands for “Good, Same, Bad,” and it’s a pairwise comparison method that Chinese AI labs, including Baidu, ByteDance, and Tencent, lean on heavily when announcing a new model generation. The way it works is simple: human evaluators, in this case professional designers, see two images side by side, one from the new model and one from a competitor or the prior generation, without knowing which is which. For each pair, they mark the new model’s output as better, roughly equal, or worse. Tencent then aggregates those judgments into a win-rate style figure, which is where the reported 30% improvement over Hy Image 3.0 comes from.

This differs from a benchmark like LMArena’s Elo ranking or a public GenEval score in a few important ways. GSB tests are run internally, on prompts the vendor chooses, evaluated by people the vendor selects, and the raw data usually isn’t published for outside verification. That doesn’t make the result meaningless. Hundreds of professional designers giving a consistent directional signal is real information. But it’s closer to a curated case study than an independent audit, and it’s worth treating Tencent’s claim that Hy Image 3.5 “ties with Seedream 5.0 Pro and edges out Nano Banana Pro and Qwen Image 3.0 Pro” as a starting hypothesis to test against your own use case, not a settled fact. If image quality is mission-critical for your product, run your own side-by-side comparison using the prompts you’ll actually ship, not marketing copy prompts.

Prerequisites and versions

Before you touch the API, get these in place. Version numbers matter here because Tencent Cloud’s SDKs move fast, and an outdated client will throw confusing authentication errors that have nothing to do with your actual API key.

• A Tencent Cloud account with identity verification completed (required before you can enable billing on any vision model)
• Python 3.10 or later, or Node.js 18 LTS or later, if you’re following the SDK examples
• The requests library (Python) version 2.31 or later, or native fetch in Node 18+
• curl 7.88 or later for the raw HTTP examples
• A credit card or supported regional payment method for postpaid billing (Tencent Cloud does not offer a free tier for Hy Image 3.5)
• Roughly $5-10 in prepaid credit for testing, since a few hundred test generations at $0.024 each add up quickly if you’re iterating on prompts

You do not need the Tencent Cloud CLI installed for this tutorial. Everything below uses direct HTTPS calls, which makes it easier to port the logic into whatever stack you’re already running, whether that’s a Python backend, a Node service, or a serverless function on AWS Lambda.

Step 1: Create and verify your Tencent Cloud account

Head to the Tencent Cloud international console and sign up with an email address. Tencent requires identity verification before it lets any account spend money on API calls, which for most non-China accounts means a phone number verification step plus a short KYC form. Budget 10-15 minutes here since the verification queue isn’t instant, and don’t skip it: without it, every API call you make later will return a permissions error that looks like a code problem but is actually an account-status problem.

Step 2: Activate the TokenHub service

TokenHub is Tencent Cloud’s unified console for generative AI models, covering both the Hunyuan LLM family and the Hy Image line. According to Tencent’s own documentation, the setup checklist starts simple: “You have registered a Tencent Cloud account and activated the TokenHub service” (Tencent Cloud documentation). From your console dashboard, search for “TokenHub” and click through to activate it. This step is free and doesn’t require billing to be enabled yet, it just unlocks the console pages you’ll need in the next few steps.

Step 3: Generate an API key

Inside the TokenHub console, navigate to the API Key management page. Tencent’s documentation puts this plainly: “You have obtained an API Key from the TokenHub console” (Tencent Cloud documentation). Click “Create Key,” give it a descriptive name (something like hy-image-tutorial-key so you can find it later), and copy the generated string immediately. Tencent shows the full key exactly once. Store it in an environment variable rather than hardcoding it into any script:

export TENCENT_TOKENHUB_KEY="your-api-key-here"

On Windows, use setx TENCENT_TOKENHUB_KEY "your-api-key-here" in PowerShell, then restart your terminal so the variable loads.

Step 4: Enable postpaid billing for vision models

This is the step most developers miss, and it’s the single most common cause of 403 errors when calling Hy Image 3.5 for the first time. Tencent’s setup guide states you must “enable postpaid billing for the corresponding model in Console – Online Inference – Vision Models” (Tencent Cloud documentation). Having an API key alone doesn’t authorize spending. Go to Console → Online Inference → Vision Models, find Hy-Image-3.5-Preview in the model list, and toggle postpaid billing on. Add a payment method if you haven’t already. Without this toggle, your API calls will authenticate fine but get rejected at the billing layer.

Step 5: Make your first authenticated request with curl

Tencent’s authentication is straightforward once billing is enabled. Per the official documentation, “the authentication method is the request header Authorization: Bearer YOUR_API_KEY” (Tencent Cloud documentation). Here’s a minimal curl call to confirm your key and billing are both working:

curl -X POST "https://api.hunyuan.cloud.tencent.com/v1/images/generations" \
  -H "Authorization: Bearer $TENCENT_TOKENHUB_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hy-image-v3.5-preview",
    "prompt": "a ceramic mug on a wooden table, morning light, product photography",
    "size": "1024x1024",
    "n": 1
  }'

If everything is wired correctly, you’ll get back a JSON payload with a base64-encoded image or a temporary download URL, depending on the response format you request. If you get a 401, your key is wrong or wasn’t loaded into the environment variable. If you get a 403 with a billing-related message, go back to Step 4.

Step 6: Text-to-image generation in Python

For anything beyond a one-off test, you’ll want a proper client function. Here’s a Python wrapper that handles the request, checks the status code, and saves the resulting image to disk:

import os
import base64
import requests

API_KEY = os.environ["TENCENT_TOKENHUB_KEY"]
ENDPOINT = "https://api.hunyuan.cloud.tencent.com/v1/images/generations"

def generate_image(prompt, size="1024x1024", out_path="output.png"):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {
        "model": "hy-image-v3.5-preview",
        "prompt": prompt,
        "size": size,
        "n": 1,
        "response_format": "b64_json",
    }
    resp = requests.post(ENDPOINT, headers=headers, json=payload, timeout=60)
    resp.raise_for_status()
    data = resp.json()
    image_b64 = data["data"][0]["b64_json"]
    with open(out_path, "wb") as f:
        f.write(base64.b64decode(image_b64))
    return out_path

if __name__ == "__main__":
    path = generate_image(
        "a minimalist running shoe on a concrete floor, studio lighting",
        size="1024x1024",
        out_path="shoe.png",
    )
    print(f"Saved image to {path}")

Run this and you should get a saved PNG in your working directory within a few seconds. Generation time for a standard 1K image typically lands under 10 seconds on Tencent’s infrastructure, based on early developer reports, though that will vary with load.

Step 7: Image-to-image generation with reference photos

Hy Image 3.5’s standout feature is accepting up to five reference images in a single request, which is useful for keeping a product’s shape, a character’s face, or a brand’s color palette consistent across a batch of generated assets. Here’s how to pass reference images alongside a prompt:

import base64

def encode_image(path):
    with open(path, "rb") as f:
        return base64.b64encode(f.read()).decode("utf-8")

def generate_with_references(prompt, reference_paths, out_path="edited.png"):
    if len(reference_paths) > 5:
        raise ValueError("Hy Image 3.5 accepts a maximum of 5 reference images per request")

    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {
        "model": "hy-image-v3.5-preview",
        "prompt": prompt,
        "reference_images": [encode_image(p) for p in reference_paths],
        "size": "2048x2048",
        "response_format": "b64_json",
    }
    resp = requests.post(ENDPOINT, headers=headers, json=payload, timeout=90)
    resp.raise_for_status()
    image_b64 = resp.json()["data"][0]["b64_json"]
    with open(out_path, "wb") as f:
        f.write(base64.b64decode(image_b64))
    return out_path

This pattern works well for e-commerce catalogs where you want the same product photographed against five different backgrounds, or for brand assets where a logo and a color swatch need to stay consistent across a batch of marketing images. It’s a similar approach to what we covered in AI product photography setup, except Hy Image 3.5 lets you feed in more reference material per call than most competing models.

Step 8: Multi-turn conversational editing

Tencent’s API documentation describes the newer Chat/Messages protocol this way: it “uses the Chat/Messages protocol, supports multimodal input, multi-turn editing context, external search enhancement, automatic size determination by area tier, and up to 4K output” (Tencent Cloud documentation). That’s a meaningfully different resolution ceiling than the 2K figure Tencent used in its initial September 22 launch announcement, and it’s worth flagging the discrepancy rather than picking one number and hoping it’s right: the original preview messaging capped output at 2K, but the current API reference for the Chat/Messages endpoint states 4K is supported. Test both and confirm against your account’s actual response before building resolution assumptions into production code.

Multi-turn editing means you can send a follow-up instruction like “make the background darker” or “remove the second object” without re-describing the entire scene. Here’s a simplified session-based approach:

CHAT_ENDPOINT = "https://api.hunyuan.cloud.tencent.com/v1/chat/completions"

def start_edit_session(prompt):
    messages = [{"role": "user", "content": prompt}]
    return call_chat_endpoint(messages), messages

def continue_edit(messages, follow_up):
    messages.append({"role": "user", "content": follow_up})
    result = call_chat_endpoint(messages)
    messages.append({"role": "assistant", "content": "[generated image]"})
    return result, messages

def call_chat_endpoint(messages):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {"model": "Hy-Image-3.5-Preview", "messages": messages}
    resp = requests.post(CHAT_ENDPOINT, headers=headers, json=payload, timeout=90)
    resp.raise_for_status()
    return resp.json()

# usage
result, history = start_edit_session("a red bicycle leaning against a brick wall")
result, history = continue_edit(history, "change the bicycle color to teal")
result, history = continue_edit(history, "add falling autumn leaves")

Keep the messages list around for the length of the editing session. Once you’re done, discard it, since resending a long history on every call adds latency and, depending on how Tencent eventually prices context tokens on this endpoint, potentially cost.

Step 9: Controlling resolution and cost together

Tencent bills Hy Image 3.5 by output image only, at three main resolution tiers on the international console. The table below reflects the pricing Tencent published alongside the September 22 launch.

Resolution	Domestic price (RMB, Tencent Cloud China)	International price (USD)
1K	¥0.15 per image	$0.024 per image
2K	¥0.15 per image	$0.024 per image
4K (reported, unconfirmed by Tencent’s own launch post)	¥0.20 per image	Not officially confirmed

Note the domestic and international consoles use separate endpoints and separate account regions. Signing up on the international console gives you USD billing at $0.024 per image regardless of whether you generate at 1K or 2K, which is a simpler pricing model than Google’s Nano Banana 2, which scales price by resolution tier. Set your size parameter deliberately: requesting 4K when you only need a thumbnail wastes both generation time and, once Tencent finalizes 4K pricing, likely money.

Step 10: Batch generation with retry logic

Preview-stage APIs rate-limit more aggressively than mature ones, and Tencent’s Hy Image 3.5 is no exception during its first weeks live. Here’s a batch script with exponential backoff that won’t crash your pipeline the first time it hits a 429:

import time

def generate_with_retry(prompt, size="1024x1024", max_retries=4):
    for attempt in range(max_retries):
        try:
            headers = {
                "Authorization": f"Bearer {API_KEY}",
                "Content-Type": "application/json",
            }
            payload = {
                "model": "hy-image-v3.5-preview",
                "prompt": prompt,
                "size": size,
                "n": 1,
                "response_format": "b64_json",
            }
            resp = requests.post(ENDPOINT, headers=headers, json=payload, timeout=60)
            if resp.status_code == 429:
                wait = 2 ** attempt
                print(f"Rate limited, waiting {wait}s (attempt {attempt + 1}/{max_retries})")
                time.sleep(wait)
                continue
            resp.raise_for_status()
            return resp.json()
        except requests.exceptions.Timeout:
            print(f"Timeout on attempt {attempt + 1}, retrying")
            time.sleep(2 ** attempt)
    raise RuntimeError(f"Failed to generate image after {max_retries} attempts")

def batch_generate(prompts, delay_between=1.5):
    results = []
    for i, prompt in enumerate(prompts):
        print(f"Generating {i + 1}/{len(prompts)}: {prompt[:50]}...")
        results.append(generate_with_retry(prompt))
        time.sleep(delay_between)
    return results

The 1.5-second delay between requests is conservative. If you’re running a high-volume pipeline, check your account’s actual rate limit in the TokenHub console rather than guessing, since preview-model quotas can change without much notice.

Step 11: Sample output and what a response looks like

A successful text-to-image response from the /v1/images/generations endpoint looks like this (truncated for readability):

{
  "created": 1790270400,
  "model": "hy-image-v3.5-preview",
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...(truncated)",
      "revised_prompt": "a ceramic mug on a wooden table, morning light, product photography, shallow depth of field"
    }
  ],
  "usage": {
    "output_images": 1,
    "billed_resolution": "1024x1024"
  }
}

Two things to watch for in that payload. First, revised_prompt shows Tencent’s model sometimes expands your prompt automatically, which is worth logging if you’re debugging inconsistent outputs across identical-looking requests. Second, the usage.billed_resolution field is your ground truth for what you’re actually being charged for, which matters if your size request gets rounded to the nearest supported tier.

Step 12: Build a complete working project

Here’s a full CLI tool that ties every piece above together: text-to-image, reference-image editing, retry logic, and cost tracking in a single file. Save it as hy_image_cli.py:

#!/usr/bin/env python3
import argparse
import base64
import json
import os
import time
from pathlib import Path

import requests

API_KEY = os.environ.get("TENCENT_TOKENHUB_KEY")
ENDPOINT = "https://api.hunyuan.cloud.tencent.com/v1/images/generations"
PRICE_PER_IMAGE_USD = 0.024
LOG_FILE = Path("hy_image_usage.log")

def log_usage(prompt, out_path):
    entry = {
        "timestamp": time.time(),
        "prompt": prompt[:80],
        "output": str(out_path),
        "cost_usd": PRICE_PER_IMAGE_USD,
    }
    with open(LOG_FILE, "a") as f:
        f.write(json.dumps(entry) + "\n")

def encode_image(path):
    with open(path, "rb") as f:
        return base64.b64encode(f.read()).decode("utf-8")

def generate(prompt, size, out_path, references=None, max_retries=4):
    if not API_KEY:
        raise EnvironmentError("Set TENCENT_TOKENHUB_KEY before running this tool")

    headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
    payload = {
        "model": "hy-image-v3.5-preview",
        "prompt": prompt,
        "size": size,
        "n": 1,
        "response_format": "b64_json",
    }
    if references:
        if len(references) > 5:
            raise ValueError("Maximum 5 reference images per request")
        payload["reference_images"] = [encode_image(p) for p in references]

    for attempt in range(max_retries):
        resp = requests.post(ENDPOINT, headers=headers, json=payload, timeout=90)
        if resp.status_code == 429:
            wait = 2 ** attempt
            print(f"Rate limited, retrying in {wait}s")
            time.sleep(wait)
            continue
        resp.raise_for_status()
        data = resp.json()
        image_b64 = data["data"][0]["b64_json"]
        Path(out_path).write_bytes(base64.b64decode(image_b64))
        log_usage(prompt, out_path)
        print(f"Saved: {out_path} (billed at ~${PRICE_PER_IMAGE_USD})")
        return out_path

    raise RuntimeError("Exceeded retry limit")

def main():
    parser = argparse.ArgumentParser(description="Hy Image 3.5 CLI generator")
    parser.add_argument("prompt", help="Text prompt for image generation")
    parser.add_argument("--size", default="1024x1024", help="Output resolution, e.g. 1024x1024")
    parser.add_argument("--out", default="output.png", help="Output file path")
    parser.add_argument("--ref", action="append", help="Reference image path (repeatable, max 5)")
    args = parser.parse_args()

    generate(args.prompt, args.size, args.out, references=args.ref)

if __name__ == "__main__":
    main()

Run it from the command line with python hy_image_cli.py "a vintage camera on a marble table" --size 2048x2048 --out camera.png. Every generation appends a line to hy_image_usage.log, so you’ll have a running cost record without needing to cross-reference the Tencent Cloud billing dashboard for every test run. Swap in the --ref flag (repeatable, up to five times) when you need reference-image conditioning.

Calling the API from Node.js

If your stack is JavaScript-based rather than Python, the same three operations (basic generation, reference-image editing, and retry handling) translate directly using native fetch, which has shipped in Node.js since version 18. Here’s a minimal client module:

const API_KEY = process.env.TENCENT_TOKENHUB_KEY;
const ENDPOINT = "https://api.hunyuan.cloud.tencent.com/v1/images/generations";

async function generateImage(prompt, size = "1024x1024") {
  const resp = await fetch(ENDPOINT, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "hy-image-v3.5-preview",
      prompt,
      size,
      n: 1,
      response_format: "b64_json",
    }),
  });

  if (resp.status === 429) {
    throw new Error("Rate limited, back off and retry");
  }
  if (!resp.ok) {
    const body = await resp.text();
    throw new Error(`Hy Image 3.5 request failed (${resp.status}): ${body}`);
  }

  const data = await resp.json();
  return data.data[0].b64_json;
}

async function saveImage(base64Data, outPath) {
  const fs = await import("fs/promises");
  await fs.writeFile(outPath, Buffer.from(base64Data, "base64"));
}

// usage
const imageB64 = await generateImage(
  "a leather backpack on a hiking trail, golden hour lighting"
);
await saveImage(imageB64, "backpack.png");
console.log("Saved backpack.png");

Wrap this in an Express route or a Next.js API handler and you have a drop-in backend endpoint for a front-end image generation feature. Just like the Python version, never call this directly from browser-side JavaScript, since that would expose your API key to anyone who opens the browser dev tools.

Why Tencent priced Hy Image 3.5 this aggressively

The $0.024-per-image international price isn’t an accident. Tencent, Alibaba, and ByteDance have spent 2026 locked in an image-model price war that mirrors the one already playing out among their large language models. Each vendor is trying to win developer mindshare in a market where GPT Image 2.5, Nano Banana 2, and Midjourney still carry premium brand recognition outside China. Undercutting on price is the fastest lever Tencent has to get foreign developers to try Hy Image 3.5 at all, especially while it’s still in preview and lacks the track record of a GPT Image or a Midjourney release.

There’s a second factor worth flagging: rising memory and wafer costs are squeezing margins across the entire AI hardware stack in 2026, and cloud vendors that own their own GPU fleets, as Tencent does, have more room to absorb a low per-image price than smaller API resellers do. That’s part of why you’re seeing similarly aggressive pricing out of Alibaba’s Qwen Image 3.0 and ByteDance’s Seedream line. If you’re building a product that leans on AI image generation as a core feature rather than an occasional utility, this competitive pressure is good news for your margins, but it also means the pricing you lock in today could shift again within a few months as the preview matures into a general-availability release.

How Hy Image 3.5 compares to other current AI image models

Here’s how Hy Image 3.5’s pricing stacks up against the other flagship image models currently on the market, based on each vendor’s published API rates as of September 2026:

Model	Vendor	Approx. price per image	Open weights?
Hy Image 3.5 Preview	Tencent	$0.024 (1K-2K, international)	No
Qwen Image 3.0	Alibaba	$0.03 (1K/2K)	Partial, see Alibaba Model Studio terms
Seedream 5.0 Lite	ByteDance	~$0.035	No
Seedream 5.0 Pro	ByteDance	~$0.045 (≤2.36MP)	No
Nano Banana 2	Google	$0.045-$0.151 (0.5K-4K)	No
GPT Image 2.5 (low-max quality)	OpenAI	$0.006-$0.211 (1024×1024)	No

On price alone, Hy Image 3.5 undercuts most of the field for standard-resolution output. What the table can’t show is quality consistency across prompt types, which is why Tencent’s own GSB comparison, imperfect as it is, matters more than the sticker price if you’re choosing a model for production work. If you’re running a pipeline that needs to hedge across providers, the approach we outlined in building a multi-model AI image pipeline applies directly here: route by cost first, then fail over to a second model when the primary one rate-limits or produces a bad result.

Common pitfalls when setting up Hy Image 3.5

These are the mistakes most likely to trip up a first integration, based on how Tencent’s documentation and console are currently structured.

• Assuming it’s self-hostable. There is no public Hy Image 3.5 checkpoint, no Hugging Face repo, and no disclosed parameter count. If your architecture depends on running the model on your own GPUs, this isn’t the model for that, at least not yet.
• Mixing up domestic and international endpoints. Tencent Cloud China (RMB billing) and Tencent Cloud International (USD billing) are separate accounts with separate consoles. An API key from one won’t authenticate against the other’s endpoint.
• Treating “preview” as production-stable. Preview-tagged models can change pricing, rate limits, or even get deprecated with short notice. Don’t hardcode this as your sole production image provider without a fallback path.
• Skipping the billing toggle. As covered in Step 4, having a valid API key is not the same as having billing enabled for the specific vision model you’re calling.
• Sending oversized reference images. Large uncompressed reference photos can push your request past payload limits. Resize references to a reasonable dimension (under 2048px on the long edge) before encoding to base64.
• Overweighting the GSB benchmark. Tencent’s 30% improvement claim and its Seedream/Nano-Banana-Pro comparison come from an internal blind test, not a public, reproducible benchmark. Validate on your own prompts before trusting it for a purchasing decision.
• Re-sending full conversation history unnecessarily. For multi-turn editing, only keep the messages relevant to the current image session in memory. Carrying old sessions forward adds latency for no benefit.

Troubleshooting Hy Image 3.5 API errors

Here are the errors you’re most likely to hit and how to resolve each one.

• 401 Unauthorized: Your API key is missing, expired, or wasn’t loaded into the environment variable. Print os.environ.get("TENCENT_TOKENHUB_KEY") to confirm it’s actually set before debugging further.
• 403 Forbidden with a billing message: Postpaid billing isn’t enabled for Hy-Image-3.5-Preview specifically. Revisit Console → Online Inference → Vision Models.
• 429 Too Many Requests: You’ve hit the preview model’s rate limit. Use the exponential backoff pattern from Step 10, and check your account’s specific quota in the TokenHub console.
• Reference image count error: You sent more than five images in the reference_images array. Trim the list.
• Timeout on 4K requests: Higher-resolution generations take longer. Bump your request timeout to at least 90 seconds for anything above 2K, and don’t assume a timeout means the generation failed server-side.
• Base64 decode errors when saving output: Confirm you’re stripping any data-URI prefix (like data:image/png;base64,) before calling base64.b64decode(), since some client libraries include it and others don’t.
• Multi-turn context not carrying over: Confirm you’re appending both the user message and a placeholder assistant entry to the messages array between calls, and that you’re reusing the same session’s history rather than starting a fresh list each time.
• Aspect ratio not matching your request: The API’s automatic size-tier rounding may snap your requested dimensions to the nearest supported tier. Check the usage.billed_resolution field in the response to see what actually got generated.
• Inconsistent output between mainland and international accounts: Some developers have reported the domestic and international deployments behaving slightly differently during the preview period. If you need identical output across regions, test both before committing to one for a global product.

For a quick lookup while you’re debugging, here’s the same information as a reference table:

HTTP status	Likely cause	Fix
401	Missing or invalid API key	Verify TENCENT_TOKENHUB_KEY is set and matches the TokenHub console
403	Postpaid billing not enabled for the model	Console → Online Inference → Vision Models → toggle billing on
429	Rate limit exceeded	Exponential backoff, or request a quota increase in the console
400 (reference image error)	More than 5 reference images sent	Trim the reference_images array to 5 or fewer
Timeout	High-resolution request under load	Increase client timeout to 90s+ for 2K/4K requests

Advanced tips for production use

Once the basic integration works, a few adjustments make Hy Image 3.5 more reliable at scale. First, build a routing layer rather than calling Tencent’s endpoint directly from your application code. Wrap the call in a function that can swap to Qwen Image 3.0 or Seedream 5.0 Lite if Hy Image 3.5 returns a 429 or a 5xx error three times in a row. This costs you almost nothing to build and saves you from a single vendor’s preview-stage instability taking down a customer-facing feature.

Second, use the five-reference-image slot deliberately rather than filling it by default. A useful pattern for brand-consistent generation is one reference for the subject, one for the background style, and one for the color palette, leaving two slots open for iteration without hitting the cap. Third, if you’re running conversational edits at scale, store session state in Redis or a similar store keyed by user or product ID, rather than keeping the messages list in memory inside a single process. That way a restart doesn’t wipe an in-progress editing session.

Finally, generate at 1K for internal review and only re-run the winning prompt at 2K or 4K for final delivery. At $0.024 a shot, the cost difference across a batch of 500 review images versus 500 final images adds up fast, and there’s rarely a reason to pay full resolution price for a draft nobody will ship.

Security and rate-limit best practices

Never expose your TENCENT_TOKENHUB_KEY in client-side code. Route all image generation through a backend service you control, the same way you would with any paid API. If you’re building a public-facing tool, add your own per-user rate limit in front of the Tencent call, both to control cost and to avoid one abusive user burning through your monthly budget. Log every request’s prompt and cost, as shown in the CLI tool above, so you have an audit trail if billing looks off at the end of the month. Since this is a preview-stage model, also keep an eye on Tencent’s changelog for the Hunyuan product line, as pricing, rate limits, and even the resolution ceiling (recall the 2K-versus-4K discrepancy from Step 8) could shift before the model exits preview status.

Verifying your full setup end to end

Before you wire Hy Image 3.5 into a real application, run through this checklist to confirm every piece from account creation to output is actually working, rather than discovering a gap once you’re mid-deploy.

• Tencent Cloud account shows “verified” status, not “pending,” in account settings
• TokenHub service shows as active in your console dashboard
• Your API key exists in the TokenHub key list and hasn’t been revoked
• Postpaid billing shows “enabled” specifically for Hy-Image-3.5-Preview under Online Inference → Vision Models
• A test curl call to /v1/images/generations returns a 200 with image data, not a 401 or 403
• The CLI tool from Step 12 runs without errors and produces a viewable PNG file
• The hy_image_usage.log file is being written to with each generation
• A multi-turn edit session correctly modifies the prior image rather than generating an unrelated new one

If any item on that list fails, work backward through the corresponding step above rather than guessing at a fix. Most first-time integration issues with Hy Image 3.5 trace back to one of two places: the billing toggle in Step 4, or a stale API key that was copied incorrectly when the TokenHub console displayed it. Both are quick to check and easy to miss under deadline pressure.

Frequently asked questions

Is Hy Image 3.5 open source or open weight?

No. As of September 2026, there is no Hugging Face repository, downloadable checkpoint, or open license for Hy Image 3.5. It’s available exclusively through Tencent Cloud’s API.

How much does Hy Image 3.5 cost per image?

On Tencent Cloud’s international console, standard-resolution output (1K-2K) costs $0.024 per image, billed only for the output, not for reference images you upload. The domestic China console prices the same tier at ¥0.15 per image.

What’s different between Hy Image 3.5 and Hy Image 3.0?

Tencent reports roughly a 30% quality improvement in an internal blind test judged by professional designers, plus new multi-turn conversational editing and support for up to five reference images per request, features not present in the 3.0 generation.

Can I use Hy Image 3.5 outside China?

Yes. Sign up through Tencent Cloud’s international console, which bills in USD and uses a separate account region from the domestic China console.

How many reference images can I upload in one request?

Up to five per request, according to Tencent Cloud’s model documentation. Exceeding that limit returns an error.

Does Hy Image 3.5 support multi-turn editing?

Yes, through the Chat/Messages protocol endpoint, which carries conversation history so you can issue follow-up edits like “change the background color” without restating the full original prompt.

What’s the maximum resolution Hy Image 3.5 supports?

Tencent’s original September 22 launch announcement cited a 2K ceiling, while the current Chat/Messages API documentation states support for up to 4K output. Confirm against your account’s live response before relying on either figure for production planning.

How does Hy Image 3.5 compare to GPT Image 2.5 and Nano Banana 2?

On price, Hy Image 3.5 is cheaper at $0.024 per standard-resolution image, versus $0.045+ for Nano Banana 2 and a wider $0.006-$0.211 range for GPT Image 2.5 depending on quality tier. On quality, Tencent’s internal GSB test placed Hy Image 3.5 slightly ahead of Nano Banana Pro, though there’s no independent public benchmark yet comparing it directly against GPT Image 2.5.

Will Hy Image 3.5 get an open-weight release?

Tencent hasn’t announced one. Tencent’s Hunyuan team has open-sourced other model families in the past, including earlier Hunyuan language and video models, so an eventual open release isn’t out of the question. As of this tutorial’s publish date, though, Hy Image 3.5 remains API-only, and there’s no confirmed roadmap for a Hugging Face release or a self-hostable checkpoint.

Related Coverage

• Grok Imagine API Setup: 13 Steps, $0.032/Image [2026]
• Gemini 3.8 Flash API: Full Setup Tutorial in 10 Steps [2026]
• Computer-Use AI Agent Setup: 13 Steps, 90 Min [2026]
• AI Red Teaming Setup: garak & PyRIT in 13 Steps [2026]
• Set Up Claude Fable 5.1 API: 12 Steps, 90 Min [2026]