IMAGE API

HY Image 3.5 Preview · API integration

Use Tencent HY Image 3.5 Preview through the media task API, with request examples, reference limits and native capability boundaries.

POST/v1/tasksMODELhy-image-v3.5-preview

Official reference hy-image-v3.5-previewChecked 2026-10-15Official docs

Code examples & responses

Request & responseExamples

POST/v1/tasks

Server-side request

curl "https://newrouters.com/v1/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "hy-image-v3.5-preview",
    "input": {
      "prompt": "Change the cup to blue while preserving its shape, lighting and background.",
      "images": ["https://your-domain.example/reference.jpg"],
      "resolution": "1k",
      "aspect_ratio": "1:1",
      "output_format": "jpeg"
    }
  }'

Server-side request

const apiBaseUrl = "https://newrouters.com";
const apiKey = process.env.API_KEY;
if (!apiKey) throw new Error("Set API_KEY in your server environment");

const response = await fetch(apiBaseUrl + "/v1/tasks", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer " + apiKey
  },
  body: JSON.stringify({
  "model": "hy-image-v3.5-preview",
  "input": {
    "prompt": "Change the cup to blue while preserving its shape, lighting and background.",
    "images": [
      "https://your-domain.example/reference.jpg"
    ],
    "resolution": "1k",
    "aspect_ratio": "1:1",
    "output_format": "jpeg"
  }
})
});

const result = await response.json();
if (!response.ok) throw new Error(JSON.stringify(result));
console.log(result);

Server-side request

import json
import os
from urllib.request import Request, urlopen

api_base_url = "https://newrouters.com"
api_key = os.environ["API_KEY"]
body = json.loads("{\"model\":\"hy-image-v3.5-preview\",\"input\":{\"prompt\":\"Change the cup to blue while preserving its shape, lighting and background.\",\"images\":[\"https://your-domain.example/reference.jpg\"],\"resolution\":\"1k\",\"aspect_ratio\":\"1:1\",\"output_format\":\"jpeg\"}}")

request = Request(
    api_base_url + "/v1/tasks",
    data=json.dumps(body).encode("utf-8"),
    headers={
    "Content-Type": "application/json",
    "Authorization": "Bearer " + api_key
    },
    method="POST",
)
with urlopen(request) as response:
    print(json.load(response))

The API origin is filled in. Set API_KEY before running. Examples never submit automatically.

ResponseSelected fields · illustrative values

202Task accepted

JSON

{
  "id": "TASK_ID",
  "status": "pending",
  "model": "hy-image-v3.5-preview",
  "result": null,
  "error": null
}

200Successful result

JSON

{
  "id": "TASK_ID",
  "status": "succeeded",
  "model": "hy-image-v3.5-preview",
  "result": {
    "assets": [
      "https://example.com/output.png"
    ]
  },
  "error": null
}

Retrieve results after submission

Request lifecycleAsynchronous media

Create a task01
POST /v1/tasks
Submit model + input. Save the returned task id.
202 · pending
Poll status02
GET /v1/tasks/{id}
Wait and poll again while pending or processing.
Wait → poll again
Read the outcome03
result.assets[] / error
Read the result for the terminal task state.
succeeded→ assetsfailed→ error

Model ID: hy-image-v3.5-preview. Supports text-to-image and reference-based editing. The platform accepts asynchronous tasks while the channel returns results synchronously. Check the live catalog and account pricing before use.

Request example

Set the platform API origin and your server-side API_KEY. Omit images for text-to-image; use publicly accessible PNG/JPEG URLs for reference editing.

curl "https://newrouters.com/v1/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "hy-image-v3.5-preview",
    "input": {
      "prompt": "Change the cup to blue while preserving its shape, lighting and background.",
      "images": ["https://your-domain.example/reference.jpg"],
      "resolution": "1k",
      "aspect_ratio": "1:1",
      "output_format": "jpeg"
    }
  }'

Retrieve the result

Poll the returned task ID until succeeded or failed. Read result.assets or error. Keep the original task ID on ambiguous failures; do not blindly resubmit paid generation.

curl "https://newrouters.com/v1/tasks/TASK_ID" -H "Authorization: Bearer $API_KEY"

Platform parameters

Field	Default	Contract
`prompt`	Required	Nonempty text; the official 100k-token context limit is not a character limit
`images`	`[]`	Up to 20 URLs; upstream inputs must be PNG/JPEG/JPG, at most 20MB each
`resolution`	`1k`	`1k`, `2k`, `4k`
`aspect_ratio`	`auto`	`auto`, `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `21:9`
`output_format`	`jpeg`	`jpeg`, `png`, `webp`; provided by the channel protocol

The platform enforces image count. Validate input format and byte size before calling; upstream enforces those constraints. The channel’s full 20-image limit remains untested. Each task requests one output; n is not exposed.

Native capabilities and integration boundaries

Tencent TokenHub supports text-to-image, reference-based generation, multi-turn editing, external search, seeds, sessions, reference resizing and watermark footnotes. Its native endpoint is /v1/wand/hunyuan-image/v35-generation, with messages input and final image frames plus assembled_history output.

This integration uses Xinhankr /v1/images/generations: images maps to image, aspect_ratio to ratio, and results use data[].url. The platform rejects messages, session, seed, use_search_tool, resize_max_pixels, footnote and custom size. Supplying a previous output as a reference enables another edit, without native conversation history.

Native dimensions allow each edge from 256 to 8192 pixels and at most 16777216 pixels total. Automatic area tiers are 1K/1.5K/2K; native 4K requires explicit size. Platform 4k is converted by the channel and has not been validated live. Resolution and aspect-ratio choices here are platform/channel presets, not native Tencent parameter enums.

Tencent’s September 22 launch article states 5 references and 2K, whereas its October 12 TokenHub API guide states 20 and 4K. These sources differ; this guide uses the newer API documentation, with channel limits still requiring live verification. Transparent backgrounds, layer decomposition and masked editing are not exposed or promised here.

Verification and errors

On 2026-10-15, one live 1K text-to-image request passed through the local public task API using the existing test key and channel account: 17.6 seconds, 1024×1024 JPEG. Reference editing, 2K/4K, maximum reference count and other encodings have not been tested live.

Native signed image URLs expire after 12 hours; save them promptly. Platform tasks return stored assets. Content filtering can return content_filter or moderation errors; HTTP success alone does not establish a valid image result. Retain the original task ID and error details.

Official sources

Checked 2026-10-15; TokenHub guide updated 2026-10-12.