Hy-Image-3.5 Preview Image Generation

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "hy-image-v3.5-preview",
    "prompt": "A golden retriever running on a beach in warm evening light",
    "size": "16:9",
    "resolution": "2K"
  }'

import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "hy-image-v3.5-preview",
        "prompt": "A golden retriever running on a beach in warm evening light",
        "size": "16:9",
        "resolution": "2K"
    }
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "hy-image-v3.5-preview",
    prompt: "A golden retriever running on a beach in warm evening light",
    size: "16:9",
    resolution: "2K"
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K..."
    }
  ]
}

POST

images

generations

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "hy-image-v3.5-preview",
    "prompt": "A golden retriever running on a beach in warm evening light",
    "size": "16:9",
    "resolution": "2K"
  }'

import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "hy-image-v3.5-preview",
        "prompt": "A golden retriever running on a beach in warm evening light",
        "size": "16:9",
        "resolution": "2K"
    }
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "hy-image-v3.5-preview",
    prompt: "A golden retriever running on a beach in warm evening light",
    size: "16:9",
    resolution: "2K"
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K..."
    }
  ]
}

This endpoint is asynchronous. After submission, obtain the task ID from data[0].task_id and use Task Query to retrieve the status and image. Poll every 3–5 seconds with a recommended overall client timeout of 5 minutes. Stop at completed or failed.

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "hy-image-v3.5-preview",
    "prompt": "A golden retriever running on a beach in warm evening light",
    "size": "16:9",
    "resolution": "2K"
  }'

import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "hy-image-v3.5-preview",
        "prompt": "A golden retriever running on a beach in warm evening light",
        "size": "16:9",
        "resolution": "2K"
    }
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "hy-image-v3.5-preview",
    prompt: "A golden retriever running on a beach in warm evening light",
    size: "16:9",
    resolution: "2K"
  })
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K..."
    }
  ]
}

Request headers

string

required

Bearer authentication: Bearer <token>, where <token> is your APIMart API Key.

Request parameters

string

required

Must be hy-image-v3.5-preview.

string

required

Text description for image generation or editing. Supports Chinese and English; must not be empty.

string

default:"auto"

Output aspect ratio or exact pixel dimensions.

Aspect ratio: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9.
Exact pixels: for example, 2000x1104, subject to the pixel limits below.
auto or omitted: the model chooses the ratio based on the prompt.

With exact pixel dimensions, resolution does not determine the output dimensions.

string

default:"1K"

Output resolution tier: 1K, 2K, or 4K; default: 1K.With exact pixel dimensions, this field does not determine the output dimensions. Always use a supported value; unsupported values return HTTP 400.

integer

Exact output width in pixels. Must be provided together with height; takes precedence over size and resolution.Width must be 256–8192, and width × height must not exceed 8,294,400. Multiples of 16 are recommended.

integer

Exact output height in pixels. Must be provided together with width.Height must be 256–8192, and width × height must not exceed 8,294,400. Multiples of 16 are recommended.

string[]

Public reference image URLs, up to 5 images. Omit for text-to-image; include for reference-based generation using the same endpoint.Supports JPEG, PNG, and WEBP. Each image should preferably be under 7MB. URLs must be publicly accessible.

string

Content you do not want in the image.

integer

Random seed; must be a non-negative integer. 0 or omission uses a random value.

integer

default:"1"

Only one image is generated per request. Must be 1; other values return HTTP 400.

Dimension selection

Priority: paired width / height → exact pixels in size → aspect ratio or auto in size combined with resolution. For exact pixels, width and height must each be 256–8192, with no more than 8,294,400 pixels in total. Multiples of 16 are recommended for both.

Exact pixel example

{
  "model": "hy-image-v3.5-preview",
  "prompt": "A minimalist seaside travel poster with a warm sunset",
  "width": 2000,
  "height": 1104
}

You may instead omit width and height and pass "size": "2000x1104".

Reference image example

{
  "model": "hy-image-v3.5-preview",
  "prompt": "Make the car in the reference image red, preserving the original background and lighting",
  "image_urls": ["https://example.com/car.png"],
  "size": "16:9",
  "resolution": "2K",
  "negative_prompt": "blur, text watermarks",
  "seed": 42,
  "n": 1
}

Replace example URLs with real publicly accessible image URLs. For multiple references, add URLs to image_urls, up to 5 images total.

Submission response

integer

Response status code; 200 indicates success.

array

Task submission result.

Show Show task fields

string

submitted means submission succeeded, not that the image has been generated.

string

Task ID for querying status and results.

Query task results

curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01K... \
  --header 'Authorization: Bearer <token>'

Successful response example (the image URL is a placeholder):

{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "result": {
      "images": [
        {
          "url": ["https://example.com/generated-image.png"]
        }
      ]
    }
  }
}

pending / processing: continue polling.
completed: read the image URL from data.result.images[0].url[0]; url is an array of strings.
failed: stop polling and read the reason from data.error.message. The charge is fully refunded. Prompt violations and content moderation failures also use this status.

Images are stored on the platform CDN. Download and save them before the time indicated by expires_at in the query result.

Billing

Billed per image. See Model Pricing for current prices.

With an aspect ratio, billing follows the resolution tier.
With exact pixel dimensions, the tier is determined by the shorter side:

Tier	Shorter side
1K	Up to 1024 pixels
2K	1025–2048 pixels
4K	Over 2048 pixels

Failed tasks receive a full refund.

Common parameter errors

The following return HTTP 400 synchronously, without creating a task or charging:

Issue	Action
Empty `prompt`	Provide a non-empty prompt
`n` is not `1`	Request only one image at a time
Negative `seed`	Use a non-negative integer; `0` means random
Unsupported `resolution`	Use `1K`, `2K`, or `4K`
Unsupported aspect ratio in `size`	Use one of the 10 ratios above or `auto`
Pixel dimensions out of range	Width and height must each be 256–8192; total pixels must not exceed 8,294,400
More than 5 reference images	Reduce `image_urls` to at most 5 images

Overview

Models

Text Series

Image Series

Video Series

Audio Series

Moderation Series

Upload Management

Task Management

Account Management

Hy-Image-3.5 Preview Image Generation

Request headers

Request parameters

Dimension selection

Exact pixel example

Reference image example

Submission response

Query task results

Billing

Common parameter errors

​Request headers

​Request parameters

​Dimension selection

​Exact pixel example

​Reference image example

​Submission response

​Query task results

​Billing

​Common parameter errors

Request headers

Request parameters

Dimension selection

Exact pixel example

Reference image example

Submission response

Query task results

Billing

Common parameter errors