# HY Image 3.5 Preview · API integration

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.

```bash
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.

```bash
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-reference:start -->
## Official sources

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

- [Tencent TokenHub Hy image guide](https://cloud.tencent.com/document/product/1823/135745)
- [Tencent HY Image 3.5 introduction](https://hunyuan.tencent.com/research/hy-image35-preview?langVersion=zh)
- [Xinhankr image protocol](https://token.xinhankr.com/docs/openai/doc0018)

<!-- official-reference:end -->

## Request examples in other languages

### JavaScript

```javascript
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);
```

### Python

```python
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))
```

## Response fields (illustrative values)

### HTTP 202

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

### HTTP 200

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