Images
POST /v1/images/generations·POST /v1/images/editsAsync 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/jsonBody#
| 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 return403 forbidden.
POST /v1/images/edits
Authorization: Bearer <JWT>
Content-Type: application/jsonBody#
| 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.