knot ai

API Reference

Image generation API

Generate images, check job status, and see your remaining credits through a JSON API over HTTPS. Create API keys in the app and always keep them on your server.

Create API keyOpenAPI JSON

Authentication

Send the key you created on the API keys page in the Authorization: Bearer ... header of every API request. Each key is shown only once, right after you create it.

Security note: Never embed API keys in browsers, mobile apps, or public repositories. If a key is exposed, revoke it immediately on the API keys page.

Generate images

POST /api/v1/images/generations

Choose a unique Idempotency-Key of 8–128 characters for each new generation request. To avoid using credits twice, reuse that key with the same parameters when you retry. Reusing a key with different parameters returns 409.

curl --request POST "https://knot-ai.xyz/api/v1/images/generations" \
  --header "Authorization: Bearer $KNOT_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: generation-20260904-001" \
  --data '{
    "prompt": "A rain-soaked city street at night, cinematic lighting",
    "model": "sdxl-lightning",
    "size": "square",
    "n": 1
  }'

Parameters

FieldValue
prompt1–2,048 characters
modelsdxl-lightning (4 credits per image) or phoenix (12 credits per image)
sizesquare (1024×1024), landscape (1280×768), or portrait (768×1280)
nAn integer from 1 to 4. The credit cost is the model's per-image price multiplied by the number of images.

Get job status

GET /api/v1/jobs/{job_id}

curl "https://knot-ai.xyz/api/v1/jobs/$JOB_ID" \
  --header "Authorization: Bearer $KNOT_API_KEY"

The status is one of reserved, running, succeeded, or failed. If a generation fails, any reserved credits are automatically returned to your balance.

Check your balance

GET /api/v1/balance

curl "https://knot-ai.xyz/api/v1/balance" \
  --header "Authorization: Bearer $KNOT_API_KEY"

Download generated images

Fetch each images[].url from the generation response with the same Bearer authentication. Images are isolated per account and can't be accessed with another user's key.

curl "https://knot-ai.xyz/api/images/$IMAGE_ID?download=1" \
  --header "Authorization: Bearer $KNOT_API_KEY" \
  --output knot-ai-image.png

Errors and rate limits

Errors use the format {"error":{"code":"...","message":"...","requestId":"..."}}. Common HTTP statuses are 400 (invalid input), 401 (authentication failed), 402 (insufficient credits), 404 (not found), 409 (idempotency conflict), 429 (rate limited), and 502 (image generation service error).

Per API key, image generation is limited to 30 requests per minute, job lookups to 120 per minute, and balance checks to 60 per minute. Limits based on image count and credit balance apply separately.