Endpoints

Images

One call starts an image run: a prompt, optionally reference images, and how many pictures you want back. The job finishes in seconds and carries the image URLs.

How it works

Pick a model from Models (or GET /models?kind=image). Without one the run uses seedream-5-lite.
count asks for several images in one run; the price multiplies by it.
referenceImageUrls takes up to eight public https URLs, or URLs from POST /files. Anything private or plain http is refused with unsafe_url before anything is charged.
The answer is a 201 job in queued or running. Follow it with GET /jobs/{id}?wait=50; the URLs land in output.imageUrls.
metadata (up to 16 strings) comes back on the job untouched, for your own order or user ids.

Generate images

post/api/v1/images

Bearer keyimages:generatecreateImage

Start an image run. The price is quoted from the model and count, charged before the provider is called, and refunded in full if the provider refuses. Reference images must be public https URLs or URLs returned by POST /files. Needs images:generate.

POST /images

curl -X POST https://kinoseed.app/api/v1/images \
  -H "Authorization: Bearer ks_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-hero" \
  -d '{
    "prompt": "a ceramic mug on a sunlit desk, product photo",
    "model": "nano-banana-pro",
    "aspect": "1:1",
    "count": 2
  }'

Parameters

Name	In	Type	Required	Description
Idempotency-Key	header	string	no	Any string of your choosing, up to 255 characters. A retry with the same key and body returns the first response (with `Idempotent-Replayed: true`) instead of starting and charging a second run. Kept for 24 hours.up to 255 characters

Request body

application/json

Field	Type	Required	Description
prompt	string	yes	up to 4000 characters
model	string	no	An image model id from GET /models. Defaults to the catalog default.
aspect	string	no	e.g. "1:1"
count	integer	no	Images per run; the price multiplies.1 to 8
referenceImageUrls	string (uri)[]	no	up to 8 items
seed	integer	no
metadata	Record<string, string>	no	Up to 16 string values the caller wants back on the job.

Responses

Status	Body	Meaning
200	Job	The provider refused the request at submission. The Job has status failed, `error` says why, and `credits.refunded` equals `credits.charged`: nothing was spent.
201	Job	The image run was started and charged. Poll GET /jobs/{id} (or use ?wait=) until status is completed or failed.
400	ErrorEnvelope	Body failed validation (`invalid_request`), the model is not in the catalog (`unknown_model`), or a URL is not public https (`unsafe_url`).
401	ErrorEnvelope	Missing, invalid or revoked key.
402	ErrorEnvelope	The balance does not cover the quote; `details` has `needed`, `balance` and `topUpUrl`.
403	ErrorEnvelope	The key lacks the images:generate scope.
409	ErrorEnvelope	A request with this Idempotency-Key is still being processed.
422	ErrorEnvelope	This Idempotency-Key was already used with a different body.
429	ErrorEnvelope	Over a rate budget; see Retry-After. Also `too_many_running` when the account already has 5 runs in progress.

Response fields

The 200 body.

Field	Type	Description
id	string
kind	"image" \| "video"
status	JobStatus
progress	integer	0 to 100
model	string
prompt	string
credits	object
credits.charged	integer
credits.refunded	integer
output	object
output.videoUrl	string \| null
output.imageUrls	string[]
output.thumbUrl	string \| null
error	string \| null	In the customer's words; null unless failed.
metadata	Record<string, string> \| null
createdAt	string (date-time)
completedAt	string (date-time) \| null
links	object
links.self	string (uri)
links.web	string (uri)