Ideogram

Ideogram V3 Character

ideogram-v3-character/edit

以参考图锁定同一角色，跨场景、姿态、光照变更保持面部与服装一致，并延续 Ideogram 的图像内文字排版优势

ideogram-v3-character ideogram-v3-character/edit

试用 ideogram-v3-character/edit

输入

作品灵感

查看全部作品

输出

image

填写参数并生成，结果会显示在这里。

价格

ideogram-v3-character/edit 每张

规格	单价
TURBO	$0.090
BALANCED	$0.130
QUALITY	$0.180

定位简介

ideogram-v3-character/edit 是面向角色一致性编辑的图像模型：上传一张源图与一个蒙版，指定要重绘的区域，再以恰好一张角色参考图作为视觉锚点，即可在保留面部、发型、服装与身形的前提下改写局部画面。适合需要把同一人物、吉祥物或虚拟形象反复用于系列素材的开发者，尤其是希望角色形象统一、同时场景与文案可变的批量生产场景。

核心亮点

角色锚定下的局部重绘——源图与蒙版定义编辑区域，参考图锁定角色身份，改场景而不换脸。
场景可变而形象不变——通过提示词替换姿态、光照与背景，人物核心特征仍由参考图约束。
可复现的批量生产——支持固定随机种子，配合风格与渲染速度档位，便于系列素材稳定复现。

能力说明

蒙版定向编辑：传入源图与同宽高比的蒙版，只重绘蒙版覆盖区域，其余画面保持不变，适合替换背景或局部元素。

单参考图角色锁定：参考图限定一张（JPEG、PNG 或 WebP，最大 10MB），据此约束重绘结果中角色的外貌特征。

提示词可控场景：最长 5000 字符的提示词描述目标场景，并可开启提示词扩展自动补全描述细节。

风格与速度档位：风格可选 AUTO、REALISTIC、FICTION，渲染速度分 TURBO、BALANCED、QUALITY，按档位区分细节程度。

适用场景

系列角色素材批量迭代——运营与设计团队以同一参考图加不同蒙版，批量产出同角色的多场景配图，用于社媒与活动页。
海报与宣传图的局部换景——在保留角色主体的前提下替换背景与布光，得到可直接投放的宣传图与带文字排版的物料。
漫画与分镜的角色一致性——作者以定妆参考图重绘分镜中的姿态与场景，产出形象连贯的连续画面用于故事板。

限制与选型建议

角色一致性并非绝对，复杂场景或极端姿态、表情下仍可能出现可见偏差；参考图需面部清晰、光照良好、遮挡较少，否则效果下降。蒙版与源图必须保持相同宽高比，参考图只接受一张。若任务是单张独立创意生成、无需锁定同一角色，改用文生图线路更合适；QUAILITY 及以上细节档位会拉长生成耗时，需在速度与质量间取舍。

近期更新

查看更新日志 →

模型上新新增 ideogram-v3-character 角色一致性生成与 ideogram-v3-character/edit… Oct 17, 2026

常见问题

查看全部常见问题 →

蒙版有什么要求？

蒙版需与原图宽高比一致，黑色区域会被重绘、白色部分保留。区域略大于角色轮廓更自然。
输出尺寸是多少？

输出跟随原图尺寸，例如 1024×768 的原图得到 1024×768 的结果。
原图里已有人物，可以替换吗？

可以，把要替换的人物涂进蒙版，并在提示词中描述新角色的动作；蒙版外的人物与背景会保留。
蒙版用什么格式？

用一张和原图宽高比相同的图片，白底上用黑色涂出要重绘的区域；本页案例使用 PNG 蒙版。

提交生成任务

POST https://api.hiapi.ai/v1/tasks

请求头

Authorizationstring必填

账号 API Key，所有请求必填。示例：Bearer YOUR_HIAPI_API_KEY。获取 API Key

Content-Typestring可选

请求体固定按 JSON 解析；如携带，仅接受 application/json（可带 charset），其他取值返回 415。示例：application/json。

Idempotency-Keystring可选

幂等键，最长 255 字节。同账户同键的重试只创建一次任务，重放返回首次 taskId。

幂等键

网络超时或客户端自动重试时，同键只创建一次任务、不会重复扣费（幂等范围 = API Key 所属账户）。建议用业务侧唯一标识做键（如 "order-42"）；同键重放返回首次 taskId，键在首次提交 24 小时后过期。详细的场景矩阵见统一异步接口介绍页。

请求体

modelstring必填

当前固定值：ideogram-v3-character/edit

routestring可选

当前固定值：default

inputobject必填

ideogram-v3-character/edit 和线路 default 的业务参数对象，见下方参数表。

seedinteger可选min 0max 2147483647

整数类型的随机种子，用于让同一提示词的生成结果可复现；取值形态为整数。

stylestring可选默认值: "AUTO"

指定生成所用的风格类型，默认 AUTO。

可选项：AUTOREALISTICFICTION

promptstring必填minLength 1maxLength 5000

描述参考角色所处的场景，即本次编辑要生成的画面内容，最长 5000 字符。

mask_urlstring必填minLength 1pattern ^https?://

指定需要重绘区域的蒙版图 URL；蒙版必须与源图保持相同宽高比。

image_urlstring必填minLength 1pattern ^https?://

待编辑的源图 URL；该图必须与蒙版保持相同宽高比。

expand_promptboolean可选默认值: true

布尔开关，控制是否使用 MagicPrompt 自动扩写提示词，默认 true。

rendering_speedstring可选默认值: "BALANCED"

指定渲染速度档位，TURBO 最快且最便宜，QUALITY 细节最丰富，不同档位价格不同；默认 BALANCED。

可选项：TURBOBALANCEDQUALITY

reference_image_urlsarray必填minItems 1maxItems 1

角色参考图数组，需且仅需一张角色参考图，支持 JPEG、PNG 或 WebP 格式，单张最大 10 MB。

Array [ string ]

callbackobject可选

终态通知配置；为空则不回调，由调用方自行查询。详见下方回调说明。

回调（Webhook）

创建任务时提供 callback.url，任务终态时 HiAPI 主动 POST 通知你的服务，可免去轮询。回调请求体与任务详情数据结构同构；签名校验、投递重试与幂等说明见统一异步接口介绍页的回调说明。

urlstring必填

callback 存在时必填；任务终态后向该 URL 发起 POST，须为合法 http(s) URL。

whenstring可选默认值: "final"

当前仅支持 final，即 success / fail 均回调。

可选项：final

storagestring可选默认值: "temp"

产物存储档位：temp（默认，保留约 7 天）或 persistent（长期保存，按大小计费）。余额不足或超出存储上限会静默降级为 temp；实际生效档位见任务详情响应。

可选项：temppersistent

请求示例

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ideogram-v3-character/edit",
  "input": {
    "style": "AUTO",
    "prompt": "…",
    "mask_url": "…",
    "image_url": "…",
    "expand_prompt": true,
    "rendering_speed": "BALANCED",
    "reference_image_urls": "…"
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "ideogram-v3-character/edit",
    input: {
      "style": "AUTO",
      "prompt": "…",
      "mask_url": "…",
      "image_url": "…",
      "expand_prompt": true,
      "rendering_speed": "BALANCED",
      "reference_image_urls": "…"
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "ideogram-v3-character/edit",
        "input": {
          "style": "AUTO",
          "prompt": "…",
          "mask_url": "…",
          "image_url": "…",
          "expand_prompt": True,
          "rendering_speed": "BALANCED",
          "reference_image_urls": "…"
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

获取任务详情

GET https://api.hiapi.ai/v1/tasks/:id

响应字段

taskIdstring必填

任务 ID，前缀固定 tk-hiapi-。

modelstring必填

解析后的模型全名。用 route 参数提交的任务返回 base@线路（如 gpt-image-2/text-to-image@ext）；否则与创建时传入的模型名一致。

routestring可选

仅当任务用显式 route 参数提交时出现，回显提交时的原值。

statusstring必填

任务状态。

状态枚举

queued 已入队，尚未开始。 handling 处理中。 archiving 处理完成，产物准备中。 success 终态：完成，产物可用（返回 output）。 fail 终态：失败（返回 error）。提交后按 status 判断：success 或 fail 为终态，其余为非终态，建议按 1~3 秒间隔轮询直至终态。成功终态后从 output[].url 下载产物，并在 expireAt 前完成下载或转存；需要长期保留时在创建任务时使用 storage: "persistent"。

creatednumber必填

任务创建时间（Unix 秒）。

completednumber必填

进入终态的 Unix 秒；非终态固定为 0。

outputarray可选

仅 status == success 时出现。产物列表，始终为数组，同一任务可能同时返回多个 type（如 video + first_frame）。

Array [ object ]

数组元素

urlstring必填

资源 URL，可直接下载。

typestring必填

当前可能值：video、image、audio、first_frame、last_frame、thumbnail，后续可能会扩展。

expireAtnumber必填

资源可访问截止时间（Unix 秒）；过期前请完成下载或转存。

errorobject可选

仅 status == fail 时出现。

codestring必填

业务错误码。

messagestring必填

错误描述。

响应示例

成功

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

处理中（非终态）

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

失败

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}