Endpoints
Jobs
Every image or video run is a job. Read it to see where it is, hold the read open until it finishes, list what the account has made, or delete it from the library.
Statuses
| Status | Meaning |
|---|---|
| queued | Accepted and charged; waiting for the provider to pick it up. |
| running | The provider is working on it. progress moves from 0 towards 100. |
| completed | Done. output holds the URLs and completedAt is set. Final. |
| failed | The provider refused or failed the run. error says why in plain words, and the credits are back. Final. |
Waiting for a result
Each read advances the job against the provider, so polling alone is enough: read it until it is final. To be told instead, register a webhook. Add ?wait=N (1 to 50 seconds) and the server holds the response, checking every 3 seconds, and answers as soon as the job is final or the time is up. One request a minute per job is then all a script needs.
Images are usually final inside one 50-second wait. Videos take one to several minutes: loop the wait. Without wait, poll no faster than every 3 seconds. Set your HTTP client's timeout above 50 seconds.
Refunds
A failed run is refunded automatically, in full, the moment it fails. The job shows it: credits.charged is what the run cost when it started and credits.refunded is what came back, so a failed job reads { "charged": N, "refunded": N }. A completed job has refunded: 0. There is nothing to claim and nothing to call.
Read a job
get/api/v1/jobs/{id}
One job, advanced against the provider on each read. With ?wait=N (1 to 50 seconds) the response is held until the job finishes or the time is up, polling every 3 seconds. Needs jobs:read.
# Hold the response up to 50 seconds while the job runs.
curl "https://kinoseed.app/api/v1/jobs/JOB_ID?wait=50" \
-H "Authorization: Bearer ks_live_YOUR_KEY"
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | yes | The job id returned when it was created. |
| wait | query | integer | no | Hold the response up to this many seconds while the job is still running.1 to 50 |
Responses
| Status | Body | Meaning |
|---|---|---|
| 200 | Job | The job. |
| 400 | ErrorEnvelope | wait is out of range. |
| 401 | ErrorEnvelope | Missing, invalid or revoked key. |
| 403 | ErrorEnvelope | The key lacks jobs:read. |
| 404 | ErrorEnvelope | No job with this id belongs to this account. |
| 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) |
List jobs
get/api/v1/jobs
The account's jobs, newest first, including runs started in the web app. Page with cursor from nextCursor. Needs jobs:read.
Newest first, up to 100 a page. Pass nextCursor back as cursor for the next page; it is null on the last one.
curl "https://kinoseed.app/api/v1/jobs?limit=20&status=completed&kind=video" \
-H "Authorization: Bearer ks_live_YOUR_KEY"
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| limit | query | integer | no | 1 to 100 |
| status | query | JobStatus | no | |
| kind | query | "image" | "video" | no | |
| cursor | query | string | no |
Responses
| Status | Body | Meaning |
|---|---|---|
| 200 | JobsListResponse | A page of jobs. |
| 400 | ErrorEnvelope | A query parameter is out of range. |
| 401 | ErrorEnvelope | Missing, invalid or revoked key. |
| 403 | ErrorEnvelope | The key lacks jobs:read. |
| 429 | ErrorEnvelope | Over a rate budget; see Retry-After. Also too_many_running when the account already has 5 runs in progress. |
Delete a job
delete/api/v1/jobs/{id}
Remove a job from the account's library. Credits are not affected: a refused run was already refunded, a finished one was delivered. Needs jobs:write.
curl -X DELETE https://kinoseed.app/api/v1/jobs/JOB_ID \
-H "Authorization: Bearer ks_live_YOUR_KEY"
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | yes | The job id returned when it was created. |
Responses
| Status | Body | Meaning |
|---|---|---|
| 200 | JobDeleteResponse | Deleted. |
| 401 | ErrorEnvelope | Missing, invalid or revoked key. |
| 403 | ErrorEnvelope | The key lacks jobs:write. |
| 404 | ErrorEnvelope | No job with this id belongs to this account. |
| 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 | |
| deleted | true |
For the job as an object, every field, see Job in the reference.