
Replace the masked sky with a clear late-afternoon sky with a few soft clouds. Keep the house, garden and shadows unchanged.
ideogram/v4.5/editIdeogram 4.5 Edit 将一张源图和文字指令转化为修改后的图片,支持可选遮罩、最多 4 张参考图与高编辑精度。它会保留未要求修改的区域,多轮编辑后依然贴近原图。
获取 API Key拖拽文件、粘贴剪贴板素材,或输入 URL。 恰好一张源图(公开 HTTP(S) URL)。
1/1 个素材
拖拽文件、粘贴剪贴板素材,或输入 URL。 可选遮罩,尺寸与源图一致:黑色 = 修改,白色 = 保留。需要 size 为 auto。
拖拽文件、粘贴剪贴板素材,或输入 URL。 最多 4 张参考图,设置遮罩时最多 3 张。仅用于引导,不会被编辑。
预计费用: 12 credits · $0.0600
提交任务时预扣积分,任务失败将全额退还。
REST API
以下流程提交一个合法的 Ideogram 4.5 Edit 请求,取得 task_id,并在异步任务结束后读取结果文件 URL。
创建 API Key,仅保存在服务端,并通过 Authorization: Bearer VIDGO_API_KEY 发送。
https://api.vidgo.ai/api/generate/submit向统一提交端点发送当前模型 ID 与 input 对象。input 只能包含本端点参数表列出的字段,其他字段会返回 400。
curl --request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "ideogram/v4.5/edit",
"input": {
"prompt": "Change the chalkboard sign text to read exactly \"FRESH BREAD DAILY\" in white chalk lettering. Keep the storefront, lighting, wood grain and every other detail unchanged.",
"edit_precision": "high",
"quality": "medium",
"size": "auto",
"n": 1,
"image_urls": [
"https://cdn.vidgo.ai/apis/models/ideogram/v4.5/edit/v1/01/input-01-source-placeholder.png"
]
}
}'读取 data.task_id,仅在 not_started 或 running 时继续轮询;finished 与 failed 都必须停止。
GET https://api.vidgo.ai/api/generate/status/{task_id}建议每 2–5 秒查询一次,并对 429/5xx 退避。也可在顶层提供 callback_url,在任务进入终态时接收回调。
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "task-example",
"status": "not_started",
"created_time": "2026-11-03T08:00:00"
}
}{
"code": 200,
"data": {
"task_id": "task-example",
"status": "finished",
"created_time": "2026-11-03T08:00:00",
"progress": 100,
"files": [
{
"file_url": "https://example.com/result.png",
"file_type": "image"
}
]
}
}展开后可查看同一 payload 的端到端脚本,包含业务 code、缺失 task_id、失败状态、异常状态和网络错误处理。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "ideogram/v4.5/edit",
"input": {
"prompt": "Change the chalkboard sign text to read exactly \"FRESH BREAD DAILY\" in white chalk lettering. Keep the storefront, lighting, wood grain and every other detail unchanged.",
"edit_precision": "high",
"quality": "medium",
"size": "auto",
"n": 1,
"image_urls": [
"https://cdn.vidgo.ai/apis/models/ideogram/v4.5/edit/v1/01/input-01-source-placeholder.png"
]
}
}
JSON
)
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
while true; do
STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
--url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
--header "Authorization: Bearer $VIDGO_API_KEY")
STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
case "$STATUS" in
finished)
printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
break
;;
failed)
printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
exit 1
;;
not_started|running)
sleep 2
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
done下表仅列出 input 对象内的公开字段。顶层 model 与可选 callback_url 请参考快速开始示例。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| input.prompt | string | 是 | – | 编辑指令,非空,最多 10,000 个字符。 |
| input.image_urls | string[] | 是 | – | 恰好一张源图,以包含 1 个公开 HTTP(S) URL 或图片 data URI 的数组提供。 |
| input.mask_url | string | 否 | – | 可选遮罩,尺寸与源图一致:黑色 = 修改,白色 = 保留。需要 size 为 auto。 |
| input.reference_image_urls | string[] | 否 | – | 0–4 张参考图(设置 mask_url 时为 0–3 张),用于引导结果,本身不会被编辑。 |
| input.edit_precision | string | 否 | regular | regular 或 high。high 需要 size 为 auto。 |
| input.quality | string | 否 | medium | very_low、low、medium 或 high,决定每张价格。 |
| input.n | integer | 否 | 1 | 图片数量,整数 1–8。 |
| input.size | string | 否 | auto | auto 保持源图尺寸;也可用预设(1:1、1:1 HD、4:3、3:4、16:9、9:16)或 WIDTHxHEIGHT(边长 ≥256 且为 32 的倍数,总像素 ≤4,194,304,比例 ≤6:1)。使用遮罩或高精度时必须为 auto。 |
提交响应返回任务标识;状态响应在任务结束时提供结果文件或失败信息。
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 业务返回码,0 或 200 表示成功。 |
| message | string | 可选的人类可读响应信息。 |
| data.task_id | string | 提交成功后用于查询状态的唯一任务 ID。 |
| data.status | string | not_started、running、finished 或 failed。 |
| data.created_time | string | 任务创建时间。 |
| data.progress | integer | 状态响应中的 0–100 进度值。 |
| data.files[] | array | finished 时按返回顺序排列的生成文件。 |
| data.files[].file_url | string | 生成文件(.png)的直接 URL。 |
| data.files[].file_type | string | 结果文件类型为 image。 |
| data.error_message | string | null | failed 状态的可读失败原因。 |
只有前两个状态可继续轮询;finished 与 failed 均为终态。
not_started已接收并排队,等待执行。
running正在生成,可以继续轮询。
finished成功终态,验证 files 并读取文件 URL。
failed失败终态,读取 error_message 并停止;预扣积分会全部退还。
| 规格 | 取值 | 说明 |
|---|---|---|
| 模型 | ideogram/v4.5/edit | Ideogram 4.5 Edit |
| 输入 | prompt + image_urls(1 张) | 可选 mask_url 与 0–4 张 reference_image_urls |
| 输出 | PNG 图片 × n(1–8) | files[] 中的位图 URL |
| quality | very_low / low / medium / high | 每张 1.6 / 6 / 12 / 44 积分 |
| size | auto / 预设 / WIDTHxHEIGHT | 默认 auto 保持源图尺寸 |
Ideogram 4.5 Edit 是 Ideogram 用于根据文字指令编辑已有图片的模型。它可对一张源图进行修改,支持可选遮罩、最多 4 张参考图以及 regular 或 high 编辑精度,按四档画质单次返回 1–8 张结果。Ideogram 的设计目标是让未修改区域保持稳定,多轮编辑不累积漂移。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
遮罩需与源图宽高一致,并同时包含黑色和白色。黑色表示要修改的区域,白色表示保留的区域。带遮罩的请求必须使用 size auto。
reference_image_urls 最多 4 张,设置 mask_url 时最多 3 张。参考图只用于引导,不会被编辑;要编辑的单张图片放在 image_urls 中。
edit_precision 设为 high 时,未改动的像素会从源图恢复,只有要求的变化不同。它需要 size 为 auto。
每张输出图片:very_low 1.6 积分($0.008),low 6 积分($0.03),medium 12 积分($0.06),high 44 积分($0.22)。总价 = 单价 × n;遮罩、参考图、精度与尺寸不影响价格。
不带遮罩的 regular 编辑可以:使用预设或自定义 WIDTHxHEIGHT(边长 ≥256 且为 32 的倍数,总像素 ≤4,194,304,比例 ≤6:1)。默认 auto 保持源图尺寸。
把上一步完成结果的 URL 作为下一次请求的 image_urls,只描述下一处修改。每一步都是独立任务,按画质 × n 计费。
可以。在指令中用引号写出新文字,并说明替换哪块招牌或标签;在该区域加上遮罩,可让照片其余部分保持不变。