图片生成与改图
适用:
nexith-image· 异步作业模型(提交 → 轮询/订阅 → 产物)
图片不是同步接口。提交请求只做三件事:校验参数、限流、预留余额并落一条作业行; 真正的生成由 worker 异步执行。完整状态机:
提交 202 → queued → running → completed
↘ failed(重试耗尽)
↘ cancelled(客户端取消)1. 文生图#
curl -X POST https://api.nexith.ai/v1/images/generations \
-H "Authorization: Bearer $NEXITH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "nexith-image",
"prompt": "a cozy reading nook by the window, soft morning light",
"size": "1024x1024"
}'响应 202:
{"id": 123, "status": "pending", "idempotency_key": "…", "created_at": "2026-11-19T02:00:00Z"}参数:
| 字段 | 必填 | 说明 |
|---|---|---|
prompt |
是 | 提示词,不能为空白 |
model |
否 | 白名单:nexith-image(默认);其他值 400 |
size |
否 | 当前固定 1024x1024 |
idempotency_key |
否 | 幂等键;同一用户重复提交返回同一作业,不重复扣费 |
2. 改图(img2img)#
改图分两步:先上传参考图拿到稳定引用,再提交改图作业。
2.1 上传参考图#
curl -X POST https://api.nexith.ai/v1/files \
-H "Authorization: Bearer $NEXITH_JWT" \
-F "file=@./reference.png" \
-F "purpose=vision"{"id":"nx-file://<uuid>","object":"file","bytes":812345,"filename":"reference.png","mime_type":"image/png","purpose":"vision"}限制:≤10 MB;仅 image/png、image/jpeg、image/webp、image/gif(按文件魔数校验)。
2.2 提交改图#
curl -X POST https://api.nexith.ai/v1/images/edits \
-H "Authorization: Bearer $NEXITH_JWT" \
-H "Content-Type: application/json" \
-d '{
"prompt": "把背景换成黄昏的海边",
"image": "nx-file://<uuid>",
"size": "1024x1024"
}'- 只接受 JWT:
nx-API Key 调用该端点返回 403(chat 站专用)。 image必须是当前用户名下的nx-file://引用;不存在/越权统一 400。- 改图与生图同 SKU、同价格、同作业流程。
3. 获取结果#
轮询#
curl https://api.nexith.ai/v1/jobs/123 \
-H "Authorization: Bearer $NEXITH_API_KEY"{
"id": 123,
"public_model": "nexith-image",
"capability": "image.generate",
"status": "completed",
"attempt": 1,
"error_message": null,
"started_at": "2026-11-19T02:00:01Z",
"completed_at": "2026-11-19T02:00:45Z",
"created_at": "2026-11-19T02:00:00Z",
"artifacts": ["https://nexith-artifacts-prod.s3.us-west-2.amazonaws.com/images/…"]
}artifacts是预签名 URL,有效期 7 天;过期后需重新生成或自行转存。error_message对外是固定不透明文案,不含上游模型名/内部错误。
订阅事件(推荐)#
curl -N https://api.nexith.ai/v1/jobs/123/events \
-H "Authorization: Bearer $NEXITH_API_KEY"帧格式见 流式协议 · 作业事件流。客户端重连会从 事件 0 回放,不会漏事件。
取消#
curl -X POST https://api.nexith.ai/v1/jobs/123/cancel \
-H "Authorization: Bearer $NEXITH_API_KEY"
# → {"id":123,"status":"cancelled"}取消后全额退还预留金额。
4. 计费与幂等#
| 主题 | 行为 |
|---|---|
| 预留 | 提交时按 $0.10/张原子预留;余额不足 402,不入队 |
| 结算 | 完成时按实际扣费 |
| 退款 | 失败、取消、服务端异常均自动全额退款 |
| 幂等 | (user_id, idempotency_key) 唯一;重复提交返回原作业,不重复扣费 |
| 限流 | 与文本同一条 (Key, 模型) 限流链,超限 429 且不锁资金 |
5. 提示词建议#
- 图片模型对具体名词 + 构图 + 光线 + 风格更敏感,避免抽象堆砌。
- 需要系列一致性时,用一张定稿图做改图(img2img)比反复文生图更稳。
- 文字渲染仍可能出错;需要精确文字时建议后期叠加,而不是让模型生成。