Ana içeriğe geç
tencent avatarı

HunyuanImage 3.0 Instruct API

tencent/hunyuan-image/v3/instruct/edit

Mevcut bir görseli yazılı bir talimat ve en fazla 3 referans görselle düzenleyin ve dönüştürün — uzun, karmaşık düzenleme yönergelerini izlemek için geliştirilmiş instruction-tuned bir checkpoint ile.

düzenleme
görsel megapikseli başına 0.09

Model girdisi

Input

The instruction describing how to edit the reference image(s).

  • https://media.modelrunner.ai/kOrNCD7gvHLVyYdDEEvZP.png

The URLs of the images to use as a reference for the edit. A maximum of 3 images are supported.

The size of the edited image. Use a preset, an explicit width/height object, or 'auto' to let the model choose from the input image.

Additional Settings

Customize your input with more control.

Min: 1 - Max: 4

The number of images to generate. Each generated image is billed.

Max: 20

The CFG scale. Higher values increase adherence to the prompt.

Whether to enable prompt expansion. This uses a large language model to expand the prompt with additional details while maintaining the original meaning. Enabled by default; disable it to have your exact wording honored.

Random seed for reproducible results. The same seed and inputs produce the same edit; leave unset for a random seed.

Safety checker can only be disabled on API call

The format of the generated image.

You need to be logged in to run this model and view results.
Log in

Model çıktısı

Output

Generated image output
Generated in 57.982 seconds
Logs (1 lines)

Örnek istekler

Örnekler

Example output 1Example output 2Example output 3Example output 4

HunyuanImage 3.0 Instruct API

HunyuanImage 3.0 Instruct is a image-to-image AI model by tencent. On ModelRunner it runs through a REST API or via MCP from any AI assistant, at $0.09 per megapixel.

POST https://queue.modelrunner.run/tencent/hunyuan-image/v3/instruct/edit

cURL

# Submit a request to the queue. Input fields go at the top level of the
# body. The optional reserved "metadata" object holds your own flat string
# tags — stored on the request, never sent to the model; filter later with
# GET https://queue.modelrunner.run/requests?metadata=<url-encoded JSON>.
curl -X POST https://queue.modelrunner.run/tencent/hunyuan-image/v3/instruct/edit \
  -H "Authorization: Key $MRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Transform this summer lakeside cabin into a cozy winter scene at dusk: snow blanketing the roof and the ground, warm …",
    "image_size": "auto",
    "image_urls": [
      "https://media.modelrunner.ai/kOrNCD7gvHLVyYdDEEvZP.png"
    ],
    "num_images": 1,
    "output_format": "png",
    "guidance_scale": 3.5,
    "enable_safety_checker": true,
    "enable_prompt_expansion": true,
    "metadata": {
      "project": "my-project"
    }
  }'
# → { "request_id": "...", "status_url": "...", "response_url": "..." }

# Poll status_url until "COMPLETED", then fetch the result
curl "https://queue.modelrunner.run/tencent/hunyuan-image/v3/instruct/edit/requests/$REQUEST_ID/status" \
  -H "Authorization: Key $MRUN_API_KEY"
curl "https://queue.modelrunner.run/tencent/hunyuan-image/v3/instruct/edit/requests/$REQUEST_ID" \
  -H "Authorization: Key $MRUN_API_KEY"

JavaScript

import { modelrunner } from "@modelrunner/client";

const result = await modelrunner.subscribe("tencent/hunyuan-image/v3/instruct/edit", {
  input: {
    "prompt": "Transform this summer lakeside cabin into a cozy winter scene at dusk: snow blanketing the roof and the ground, warm …",
    "image_size": "auto",
    "image_urls": [
      "https://media.modelrunner.ai/kOrNCD7gvHLVyYdDEEvZP.png"
    ],
    "num_images": 1,
    "output_format": "png",
    "guidance_scale": 3.5,
    "enable_safety_checker": true,
    "enable_prompt_expansion": true
  },
});
console.log(result);

Python

import os
import requests

headers = {"Authorization": f"Key {os.environ['MRUN_API_KEY']}"}

submitted = requests.post(
    "https://queue.modelrunner.run/tencent/hunyuan-image/v3/instruct/edit",
    headers=headers,
    json={
      "prompt": "Transform this summer lakeside cabin into a cozy winter scene at dusk: snow blanketing the roof and the ground, warm …",
      "image_size": "auto",
      "image_urls": [
        "https://media.modelrunner.ai/kOrNCD7gvHLVyYdDEEvZP.png"
      ],
      "num_images": 1,
      "output_format": "png",
      "guidance_scale": 3.5,
      "enable_safety_checker": true,
      "enable_prompt_expansion": true
    },
).json()

# Poll submitted["status_url"] until "COMPLETED", then:
result = requests.get(submitted["response_url"], headers=headers).json()

Input parameters

Input parameters of HunyuanImage 3.0 Instruct
NameTypeRequiredDescription
promptstringyesThe instruction describing how to edit the reference image(s).
image_urlsarrayyesThe URLs of the images to use as a reference for the edit. A maximum of 3 images are supported.
image_sizeenumnoThe size of the edited image. Use a preset, an explicit width/height object, or 'auto' to let the model choose from the input image. One of: auto, square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9. Default: "auto".
num_imagesintegernoThe number of images to generate. Each generated image is billed. Default: 1.
guidance_scalenumbernoThe CFG scale. Higher values increase adherence to the prompt. Default: 3.5.
enable_prompt_expansionbooleannoWhether to enable prompt expansion. This uses a large language model to expand the prompt with additional details while maintaining the original meaning. Enabled by default; disable it to have your exact wording honored. Default: true.
seedintegernoRandom seed for reproducible results. The same seed and inputs produce the same edit; leave unset for a random seed.
enable_safety_checkerbooleannoIf set to true, the safety checker will be enabled. Default: true.
output_formatenumnoThe format of the generated image. One of: jpeg, png. Default: "png".

Machine-readable: OpenAPI schema · llms.txt

Use HunyuanImage 3.0 Instruct from Claude & Cursor (MCP)

Point Claude Code, Claude Desktop, Cursor, or any MCP client at the ModelRunner MCP server and HunyuanImage 3.0 Instruct becomes a tool your assistant can call directly — it authorizes via OAuth (no API key in config) and runs this model with the run_model tool using the endpoint tencent/hunyuan-image/v3/instruct/edit.

MCP client config (Claude Desktop, Cursor)

{
  "mcpServers": {
    "modelrunner": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.modelrunner.run/mcp"]
    }
  }
}

Claude Code

claude mcp add --transport http modelrunner https://mcp.modelrunner.run/mcp

Then ask your assistant, for example: “Run tencent/hunyuan-image/v3/instruct/edit on ModelRunner to generate image”. MCP setup guide.

Model Detayları

Model Detayları

HunyuanImage 3.0 Instruct, mevcut bir görseli yazılı bir talimata göre düzenler. Bir ila üç referans görsel verin ve istediğiniz değişikliği tarif edin — "bu çizimi gerçekçi bir fotoğrafa dönüştür", "arka planı karlı bir sokakla değiştir", "ceketi kırmızı yap ve bir atkı ekle" — model de düzenlemenizi uygulayan yeni bir görsel döndürür. 80 milyar parametreli HunyuanImage 3.0 temel modelinin instruction-tuned checkpoint’idir; bu yüzden uzun, çok parçalı düzenleme yönergelerini okur ve render’dan önce değişikliği planlar, her talimatı tek geçişli bir düzenlemeye kıyasla daha sadık biçimde izler. Birden fazla referans görsel vermek, içeriği tek çağrıda bunlar arasında birleştirmesini ya da aktarmasını sağlar.

Kaynak görselleri `image_urls` alanında dizi olarak verin (en fazla 3). Prompt genişletme varsayılan olarak açıktır: bir dil modeli, düzenleme çalışmadan önce kısa talimatları detaylandırır — tam olarak yazdığınız ifadenin korunmasını istiyorsanız `enable_prompt_expansion` alanını `false` yapın. Modelin sonucu girdiye göre boyutlandırması için `image_size` alanını `auto` bırakın ya da bir hazır ayar (`square_hd`, `portrait_16_9`, `landscape_16_9`) veya açıkça bir `{width, height}` nesnesi vererek tuvali sabitleyin.

## En uygun olduğu işler - Mevcut bir görsele tarif edilen bir değişikliği uygulamak — yeniden tarzlamak, rengini değiştirmek, nesne eklemek ya da çıkarmak, arka planı değiştirmek - Çizimleri, eskizleri ya da render’ları fotogerçekçi görsellere çevirmek ve tersi - Basit bir düzenleme modelinin bir kısmını atlamaya eğilimli olduğu uzun, çok parçalı düzenleme talimatları - İki ya da üç referans görsel arasında içeriği tek düzenlemede birleştirmek ya da aktarmak - Düzenlemenin kesin yazılı yönergeleri izlemesi gereken editoryal ve ürün rötuşu

## Şu durumlarda başka bir model seçin - Kaynak görseliniz yoksa ve yalnızca metin prompt’undan üretmek istiyorsanız — HunyuanImage 3.0 Instruct text-to-image varyantını kullanın - Yalnızca çizilen bir bölgenin değiştiği, piksel hassasiyetinde maskeli inpainting gerekiyorsa — bu endpoint maske almaz, özel bir inpainting modeli kullanın - Bir görseli içeriğini değiştirmeden büyütmek ya da restore etmek istiyorsanız — bir upscaling ya da restorasyon modeli kullanın - Video gerekiyorsa — bir image-to-video modeli kullanın

## İpuçları - Düzenlemeyi, görselde ne olduğuna atıf yapan net bir talimat olarak yazın; muhakeme adımı anahtar kelime listelerinden çok eksiksiz ve yapılandırılmış yönergeleri ödüllendirir - Ana görseli `image_urls` içinde ilk sıraya koyun; modelin içerik ya da stil ödünç almasını istediğinizde en fazla iki referans daha ekleyin - Kısa talimatlarda `enable_prompt_expansion` alanını açık bırakın; talimatınız zaten kesinse ve kelimesi kelimesine korunmasını istiyorsanız `false` yapın - Girdinin oranlarını korumak için `image_size` alanını `auto` bırakın ya da belirli bir çıktı boyutunu sabitlemek için bir hazır ayar / `{width, height}` nesnesi verin - Her çıktı görseli megapiksel başına faturalanır; bu yüzden daha büyük boyutlar ve daha yüksek `num_images` daha pahalıya gelir

ModelRunner JavaScript client ile çalıştırmak için: ```js import { modelrunner } from "@modelrunner/client";

const result = await modelrunner.subscribe("tencent/hunyuan-image/v3/instruct/edit", { input: { prompt: "Turn this artwork into a realistic photograph", image_urls: ["https://media.modelrunner.ai/example-source.png"], num_images: 1, output_format: "png", }, }); ```