NNexithDocs
状态控制台 ↗
概览与快速开始模型目录指南API 参考集成OAuth2 / OIDC

图片生成与改图

适用: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)比反复文生图更稳。
  • 文字渲染仍可能出错;需要精确文字时建议后期叠加,而不是让模型生成。