NNexithDocs
StatusDashboard ↗
Overview & quickstartModel catalogGuidesAPI referenceIntegrationsOAuth2 / OIDC

Image generation and editing

Applies to: nexith-image · Async job model (submit → poll/subscribe → artifact)

Images are not a synchronous API. A submission request does only three things: validate parameters, apply rate limiting, and reserve balance while writing a job row; the actual generation runs asynchronously in a worker. Full state machine:

提交 202 → queued → running → completed
                          ↘ failed(重试耗尽)
        ↘ cancelled(客户端取消)

1. Text-to-image#

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"
  }'

Response 202:

{"id": 123, "status": "pending", "idempotency_key": "…", "created_at": "2026-11-19T02:00:00Z"}

Parameters:

Field Required Description
prompt Yes Prompt; must not be blank
model No Allowlist: nexith-image (default); any other value returns 400
size No Currently fixed at 1024x1024
idempotency_key No Idempotency key; repeated submissions by the same user return the same job with no duplicate charge

2. Image editing (img2img)#

Editing takes two steps: first upload a reference image to obtain a stable reference, then submit the editing job.

2.1 Upload the reference image#

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"}

Limits: ≤10 MB; image/png, image/jpeg, image/webp, image/gif only (validated by file magic bytes).

2.2 Submit the edit#

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 only: calling this endpoint with an nx- API key returns 403 (chat site only).
  • image must be an nx-file:// reference owned by the current user; nonexistent and unauthorized references both return 400.
  • Editing and generation share the same SKU, price, and job flow.

3. Getting results#

Polling#

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 are presigned URLs valid for 7 days; after expiry they must be regenerated or copied elsewhere.
  • error_message is a fixed, opaque message for external consumption and contains no upstream model name or internal error text.
curl -N https://api.nexith.ai/v1/jobs/123/events \
  -H "Authorization: Bearer $NEXITH_API_KEY"

See Streaming protocol · Job event stream for the frame format. A reconnecting client replays from event 0, so no events are missed.

Cancellation#

curl -X POST https://api.nexith.ai/v1/jobs/123/cancel \
  -H "Authorization: Bearer $NEXITH_API_KEY"
# → {"id":123,"status":"cancelled"}

Cancellation refunds the full reserved amount.


4. Billing and idempotency#

Topic Behavior
Reservation Atomically reserved at $0.10/image on submission; insufficient balance returns 402 and nothing is enqueued
Settlement Charged based on actual usage on completion
Refund Failures, cancellations, and server-side exceptions all trigger an automatic full refund
Idempotency (user_id, idempotency_key) is unique; repeated submissions return the original job with no duplicate charge
Rate limiting Uses the same (key, model) rate limiting chain as text; exceeding it returns 429 without locking funds

5. Prompt tips#

  • Image models respond more strongly to concrete nouns + composition + lighting + style; avoid piling up abstractions.
  • When you need series consistency, using a finalized image for img2img is more reliable than repeated text-to-image generations.
  • Text rendering can still fail; if you need exact text, add it in post-processing rather than asking the model to generate it.