NNexithDocs
StatusDashboard ↗
Overview & quickstartModel catalogGuidesAPI referenceIntegrationsOAuth2 / OIDC

Images

POST /v1/images/generations · POST /v1/images/edits Async jobs: submission returns 202, artifacts are retrieved via /v1/jobs/:id


POST /v1/images/generations#

Submits an image generation job.

POST /v1/images/generations
Authorization: Bearer nx-...
Content-Type: application/json

Body#

Field Type Required Description
prompt string ✅ Prompt; blank values are rejected
model string — Defaults to nexith-image; values outside the allowlist return 400
size string — Defaults to 1024x1024
idempotency_key string — Idempotency key; the same key from the same user returns the original job

Response 202#

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

Errors#

Status code Scenario
400 invalid_request prompt is empty / model not in the allowlist
402 insufficient_balance Insufficient balance (rejected before enqueueing)
429 rate_limit_exceeded RPM/TPM exceeded (no funds are locked)
502/503 inference_unavailable / model_overloaded Model catalog unavailable

POST /v1/images/edits#

Submits an image editing job (img2img).

JWT only (chat site). Calls made with an nx- API key return 403 forbidden.

POST /v1/images/edits
Authorization: Bearer <JWT>
Content-Type: application/json

Body#

Field Type Required Description
prompt string ✅ Editing instruction
image string ✅ nx-file://<uuid> reference (upload first via POST /v1/files)
size string — Defaults to 1024x1024
idempotency_key string — Idempotency key

Response#

Also a 202 plus a job object; the rest of the flow is identical to generation.

Errors#

Status code Scenario
400 invalid_request image is not a valid nx-file:// reference, or does not belong to the current user
403 forbidden Called with an nx- key
402 insufficient_balance Insufficient balance

Artifacts#

Once the job completes, the artifacts array in GET /v1/jobs/:id contains presigned URLs:

https://nexith-artifacts-prod.s3.us-west-2.amazonaws.com/images/<user>/<uuid>.png?X-Amz-…

Valid for 7 days. After expiry they must be regenerated; for long-term storage, copy the artifacts to your own storage as they are produced.


Billing#

Item Price
Generation / editing $0.10 / image

Reserved at submission, settled on completion, fully refunded on failure or cancellation. See the Image guide.