HY Image 3.0 API 接口、参数 & 代码示例

tencent/hy-image-v3

Hunyuan Image 3.0（腾讯混元图像3.0）是腾讯混元大模型团队推出的一款旗舰级开源图像生成与编辑大模型。它在技术架构和生成范式上做出了重大突破，是当前开源社区中最强且规模最大的图像生成模型之一。

模型 ID: tencent/hy-image-v3
模型系列: Hunyuan
更新日期: 2026-08-18
模型能力: 图片生成
模型价格（每张）: ¥ 0.25

HY Image 3.0 模型介绍：

核心技术架构与特色

统一的原生多模态自回归架构

区别于传统 DiT（Diffusion Transformer）： 并没有采用主流的扩散模型路线，而是采用了统一的自回归（Autoregressive）框架。这种设计在一个模型中直接并紧密地对文本理解、视觉理解与图像生成进行联合建模，实现了真正意义上的原生多模态融合。

超大规模 MoE（专家混合）架构

开源界最大： 模型拥有 800 亿（80B）总参数量，内置 64 个专家模块。
高效激活： 采用 MoE 机制，在处理单 Token 推理时仅激活约 130 亿（13B）参数，兼顾了巨大的知识容量与较高的计算效率。

智能 CoT（思维链）推理与“先思考，后生成”

模型集成了强大的视觉与世界知识推理能力。
自动提示补全： 当用户输入简短或模糊的提示词（Prompt）时，模型会先基于内部知识进行自重写与补全，自动丰富构图、光照、材质等细节。
图生图与编辑能力（HunyuanImage 3.0-Instruct）： 在图像编辑任务中引入“先思考，后编辑”的思维链机制，先分析用户输入的图片与修改意图，生成结构化的编辑逻辑，再精准执行改动。

主要功能场景

文生图（Text-to-Image）： 具备极高的提示词遵循度（Prompt Following）与摄影级真实感，能处理复杂的场景描述、多主体互动及细腻的美学风格。
精确图像编辑（Image Editing）： 支持增、删、修改、人物改动、风格转换及老照片修复等，能在修改局部要素的同时，极好地保持非编辑区域的一致性。
多图融合（Multi-Image Synthesis）： 支持同时输入多张参考图（最多支持 3 张），智能提取不同图片的元素并整合生成一张自然连贯的新图。

行业表现与业界地位

维度	实际表现
开源开放性	权重完全开源（包括文生图和 Instruct 图生图版本），支持社区部署与二次微调。
盲测竞技场成绩	在全球权威大模型评测平台 LMArena 的文生图及图像编辑（Image Edit）榜单中均跻身全球第一梯队，表现媲美甚至超越顶尖闭源模型。
后训练优化	引入自研算法（如 MixGRPO）和千万级高质数据进行强化学习对齐，显著提升生成图的美学度与用户偏好吻合度。

API 接口地址：

https://wcode.net/api/gpt/v1/images/generations

此 API 接口兼容 OpenAI 的 Images 接口规范，可直接使用 OpenAI 的 SDK 来调用。仅需替换以下配置即可：

base_url 替换为 https://wcode.net/api/gpt/v1

api_key 替换为从 https://platform.wcode.net 获取到的 API Key

具体可参考下方的各编程语言代码示例中的 OpenAI SDK 调用示例。

请求方法：

POST

各编程语言代码示例：

# TODO: 以下代码中的 API_KEY 需要替换，获取 API Key 入口：https://platform.wcode.net

curl --request POST 'https://wcode.net/api/gpt/v1/images/generations' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer API_KEY' \
  --data '{
    "model": "tencent/hy-image-v3",
    "prompt": "一只可爱的小猫咪，坐在阳光明媚的窗台上，背景是蓝天白云"
  }'

import Foundation

let headers = [
  "Authorization": "Bearer API_KEY",  // TODO: 这里的 API_KEY 需要替换，获取 API Key 入口：https://platform.wcode.net
  "Content-Type": "application/json"
]
let parameters = [
  "model": "tencent/hy-image-v3",
  "prompt": "一只可爱的小猫咪，坐在阳光明媚的窗台上，背景是蓝天白云"
] as [String : Any]

let postData = try! JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://wcode.net/api/gpt/v1/images/generations")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 60.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if let data = data {
    print(String(data: data, encoding: .utf8) ?? "")
  }
})
dataTask.resume()

import 'dart:convert';
import 'package:http/http.dart' as http;

Future<void> main() async {
  final response = await http.post(
    Uri.parse('https://wcode.net/api/gpt/v1/images/generations'),
    headers: {
      'Authorization': 'Bearer API_KEY',  // TODO: 这里的 API_KEY 需要替换，获取 API Key 入口：https://platform.wcode.net
      'Content-Type': 'application/json',
    },
    body: jsonEncode({
      'model': 'tencent/hy-image-v3',
      'prompt': '一只可爱的小猫咪，坐在阳光明媚的窗台上，背景是蓝天白云',
    }),
  );

  print(response.body);
}

require 'uri'
require 'json'
require 'net/http'

url = URI("https://wcode.net/api/gpt/v1/images/generations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer API_KEY'  # TODO: 这里的 API_KEY 需要替换，获取 API Key 入口：https://platform.wcode.net
request["Content-Type"] = 'application/json'
request.body = {
  model: 'tencent/hy-image-v3',
  prompt: '一只可爱的小猫咪，坐在阳光明媚的窗台上，背景是蓝天白云'
}.to_json

response = http.request(request)
puts response.read_body

#[tokio::main]
pub async fn main() {
  let client = reqwest::Client::new();
  let response = client.post("https://wcode.net/api/gpt/v1/images/generations")
    .header("Authorization", "Bearer API_KEY")  // TODO: 这里的 API_KEY 需要替换，获取 API Key 入口：https://platform.wcode.net
    .header("Content-Type", "application/json")
    .json(&serde_json::json!({
      "model": "tencent/hy-image-v3",
      "prompt": "一只可爱的小猫咪，坐在阳光明媚的窗台上，背景是蓝天白云"
    }))
    .send()
    .await
    .unwrap();

  println!("{}", response.text().await.unwrap());
}

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://wcode.net/api/gpt/v1/images/generations");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Content-Type: application/json");
headers = curl_slist_append(headers, "Authorization: Bearer API_KEY");  // TODO: 这里的 API_KEY 需要替换，获取 API Key 入口：https://platform.wcode.net
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

const char *data = "{\"model\":\"tencent/hy-image-v3\",\"prompt\":\"一只可爱的小猫咪，坐在阳光明媚的窗台上，背景是蓝天白云\"}";
curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, data);

CURLcode ret = curl_easy_perform(hnd);

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  url := "https://wcode.net/api/gpt/v1/images/generations"
  payload := []byte(`{"model":"tencent/hy-image-v3","prompt":"一只可爱的小猫咪，坐在阳光明媚的窗台上，背景是蓝天白云"}`)

  req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
  req.Header.Add("Authorization", "Bearer API_KEY")  // TODO: 这里的 API_KEY 需要替换，获取 API Key 入口：https://platform.wcode.net
  req.Header.Set("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  respBody, _ := io.ReadAll(res.Body)

  fmt.Println(string(respBody))
}

using System.Net.Http.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer API_KEY");  // TODO: 这里的 API_KEY 需要替换，获取 API Key 入口：https://platform.wcode.net

var payload = new {
  model = "tencent/hy-image-v3",
  prompt = "一只可爱的小猫咪，坐在阳光明媚的窗台上，背景是蓝天白云"
};

var response = await client.PostAsJsonAsync("https://wcode.net/api/gpt/v1/images/generations", payload);
Console.WriteLine(await response.Content.ReadAsStringAsync());

var client = new RestClient("https://wcode.net/api/gpt/v1/images/generations");

var request = new RestRequest("", Method.Post);
request.AddHeader("Authorization", "Bearer API_KEY");  // TODO: 这里的 API_KEY 需要替换，获取 API Key 入口：https://platform.wcode.net
request.AddHeader("Content-Type", "application/json");
request.AddJsonBody(new {
  model = "tencent/hy-image-v3",
  prompt = "一只可爱的小猫咪，坐在阳光明媚的窗台上，背景是蓝天白云"
});

var response = client.Execute(request);
Console.WriteLine(response.Content);

const axios = require('axios');

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://wcode.net/api/gpt/v1/images/generations',
  headers: {
    'Authorization': 'Bearer API_KEY',  // TODO: 这里的 API_KEY 需要替换，获取 API Key 入口：https://platform.wcode.net
    'Content-Type': 'application/json'
  },
  data: {
    model: 'tencent/hy-image-v3',
    prompt: '一只可爱的小猫咪，坐在阳光明媚的窗台上，背景是蓝天白云'
  }
};

axios.request(config).then((response) => {
  console.log(JSON.stringify(response.data));
}).catch((error) => {
  console.log(error);
});

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"model\":\"tencent/hy-image-v3\",\"prompt\":\"一只可爱的小猫咪，坐在阳光明媚的窗台上，背景是蓝天白云\"}");

Request request = new Request.Builder()
  .url("https://wcode.net/api/gpt/v1/images/generations")
  .post(body)
  .addHeader("Authorization", "Bearer API_KEY")  // TODO: 这里的 API_KEY 需要替换，获取 API Key 入口：https://platform.wcode.net
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

$client = new \GuzzleHttp\Client();

$response = $client->post('https://wcode.net/api/gpt/v1/images/generations', [
  'headers' => [
    'Authorization' => 'Bearer API_KEY',  // TODO: 这里的 API_KEY 需要替换，获取 API Key 入口：https://platform.wcode.net
  ],
  'json' => [
    'model' => 'tencent/hy-image-v3',
    'prompt' => '一只可爱的小猫咪，坐在阳光明媚的窗台上，背景是蓝天白云',
  ],
]);

echo $response->getBody();

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://wcode.net/api/gpt/v1/images/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 5,
  CURLOPT_TIMEOUT => 300,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'tencent/hy-image-v3',
    'prompt' => '一只可爱的小猫咪，坐在阳光明媚的窗台上，背景是蓝天白云',
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer API_KEY",  // TODO: 这里的 API_KEY 需要替换，获取 API Key 入口：https://platform.wcode.net
    "Content-Type: application/json",
  ],
]);

$response = curl_exec($curl);
$error = curl_error($curl);

curl_close($curl);

if ($error) {
  echo "cURL Error #:" . $error;
} else {
  echo $response;
}

import requests
import json

url = "https://wcode.net/api/gpt/v1/images/generations"

headers = {
  "Authorization": "Bearer API_KEY",  # TODO: 这里的 API_KEY 需要替换，获取 API Key 入口：https://platform.wcode.net
  "Content-Type": "application/json",
}

payload = {
  "model": "tencent/hy-image-v3",
  "prompt": "一只可爱的小猫咪，坐在阳光明媚的窗台上，背景是蓝天白云"
}

response = requests.post(url, headers=headers, json=payload)

print(json.dumps(response.json(), indent=4, ensure_ascii=False))

from openai import OpenAI

client = OpenAI(
  base_url="https://wcode.net/api/gpt/v1",
  api_key="API_KEY"  # TODO: 这里的 API_KEY 需要替换，获取 API Key 入口：https://platform.wcode.net
)

response = client.images.generate(
  model="tencent/hy-image-v3",
  prompt="一只可爱的小猫咪，坐在阳光明媚的窗台上，背景是蓝天白云",
)

print(response.data[0].url)