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). imagemust be annx-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/…"]
}artifactsare presigned URLs valid for 7 days; after expiry they must be regenerated or copied elsewhere.error_messageis a fixed, opaque message for external consumption and contains no upstream model name or internal error text.
Subscribing to events (recommended)#
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.