hy-image

文生图与参考图生图
参考图最多 5 张
支持 1K / 2K / 4K，也可直接给精确像素

POST/v1/images/generations

认证

string必填

所有接口均使用 Bearer Token 进行认证。

获取 API Key：访问控制台创建。

请求时在请求头中添加：

Authorization: Bearer YOUR_OAIRoute_KEY

请求结构

请求体是平铺的 JSON，创作字段与输出字段都在顶层，没有 content 数组包装。

支持的场景

场景	字段组合
文生图	`prompt`
参考图生图	`prompt` + `image`

size 写 auto 或省略时，文生图回落为 1:1，图生图跟随参考图比例。

尺寸优先级从高到低：成对的 width / height → 精确像素 size → 比例配合 resolution。使用精确像素时 resolution 不参与尺寸计算。

Scenario	Field combination
Text to image	`prompt`
Reference-image to image	`prompt` + `image`

When size is auto or omitted, text to image falls back to 1:1 and image to image follows the reference image's ratio.

Size precedence, highest first: the width / height pair → exact-pixel size → ratio combined with resolution. With exact pixels, resolution doesn't participate in determining size.

请求参数

提交成功只返回任务 ID，不含图片本身。拿结果用 task_id 轮询获取任务状态，图片地址在 result.images[0].url，该地址会过期，请及时转存。

string必填

取值为 hy-image-v3.5-preview。

string必填

画面描述，中英文均可。

string可选

默认 auto。

可写宽高比 1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9，可写精确像素如 2000x1104，也可写 auto。

string可选

取值 1K（默认）、2K、4K，其他值返回 400。

integer可选

必须与 height 成对使用。

范围 256 到 8192，宽高乘积不超过 8294400，建议取 16 的倍数。

integer可选

约束与 width 相同，必须成对提供。

string[]可选

参考图，最多 5 张公网地址。

格式 JPEG、PNG、WEBP，单张建议不超过 7MB。

string可选

反向描述。

integer可选

随机种子，非负整数。0 或省略表示随机。

integer可选

只能为 1。

计费

按张计费。比例形式按 resolution 档位计费；精确像素按短边判档：不超过 1024 为 1K，1025 到 2048 为 2K，超过 2048 为 4K。

失败任务全额退款。

响应

提交成功返回受理结构：

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

integer总是返回

状态码，200 表示任务已受理。

array总是返回

本次提交的任务列表。

data[] 的元素字段 · 2 项

string总是返回

受理状态，提交成功时为 submitted。

string总是返回

任务 ID，用它轮询结果。

完成态返回：

{
  "code": 200,
  "data": {
    "id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        { "url": ["https://cdn.oairoute.com/f/image/task_01K8_0.png"], "expires_at": 1763174708 }
      ]
    },
    "created": 1763088289,
    "completed": 1763088302
  }
}

A successful submission returns an accepted structure:

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

integerAlways

The status code; 200 means the task was accepted.

arrayAlways

The list of tasks submitted this time.

data[] 的元素字段 · 2 项

stringAlways

The acceptance status; submitted on success.

stringAlways

The task ID; use it to poll for the result.

The completed state returns:

{
  "code": 200,
  "data": {
    "id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        { "url": ["https://cdn.oairoute.com/f/image/task_01K8_0.png"], "expires_at": 1763174708 }
      ]
    },
    "created": 1763088289,
    "completed": 1763088302
  }
}

错误码

HTTP	含义
400	参数错误，type 为 invalid_request_error
401	Token 缺失或无效，type 为 authentication_error
402	余额不足，type 为 payment_required
429	触发限流

更多状态码与重试建议见错误码与限流，常见报错的排查步骤见常见问题。

HTTP	Meaning
400	Invalid parameters, with type `invalid_request_error`
401	Token missing or invalid, with type `authentication_error`
402	Insufficient balance, with type `payment_required`
429	Rate limit hit

For more status codes and retry guidance see Error codes and rate limits; for troubleshooting steps on common errors see the FAQ.

支持的模型列表

模型 ID	定位
`hy-image-v3.5-preview`	当前唯一型号

完整模型目录（含价格、分辨率上限）可读取 GET https://api.oairoute.com/api/pricing。

hy-image

认证

请求结构

支持的场景

请求参数

计费

响应

错误码

支持的模型列表

使用示例