Create and Retrieve
All three products use one Creations API, so video, image, and app results share the same list, detail, and output workflow.
Upload Source Files
All products accept input_file_ids. Upload a file first:
curl -s "https://api.kpainter.ai/openapi/v1/files" \ -H "Authorization: Bearer $KPAINTER_API_KEY" \ -F "file=@./handbook.pdf"Example response:
{ "file_id": "file_xxx", "name": "handbook.pdf", "mime_type": "application/pdf", "size_bytes": 248391}Use the returned file_id only within creations owned by the same account.
Create
POST /creationsCommon fields:
| Field | Required | Meaning |
|---|---|---|
| type | yes | video, image, or app |
| prompt | yes | What to create |
| instructions | no | Additional requirements |
| input_file_ids | no | Previously uploaded source IDs |
| max_credits | no | Maximum credits authorized for this task |
| video / image / app | yes | Exactly one settings object matching type |
Example:
{ "type": "app", "prompt": "Build a safety quiz with immediate feedback from the handbook", "input_file_ids": ["file_xxx"], "app": { "language": "en" }}List and Get
GET /creations?page=1&page_size=20GET /creations?type=video&page=1&page_size=20GET /creations/{id}Useful detail fields:
| Field | Meaning |
|---|---|
| status | planning, producing, paused, ready, or failed |
| progress_pct | Monotonic progress from 0 to 100 |
| estimated_remaining_seconds | Present only when reliable |
| estimated_credits | Current estimate for this task |
| actual_credits | Net credits for a successful task |
| has_usable_delivery | Whether a usable result already exists |
| available_actions | Actions that are currently safe to call |
| review | A safe Explainer Video outline when available |
| result_code | A user-safe outcome code |
Ordinary failures omit actual_credits. An unreliable ETA is omitted rather than guessed.
Read Outputs
GET /creations/{id}/outputsDisplay only returned outputs. Do not infer a URL or use an unfinished intermediate artifact.
A Stable Client Flow
- Read capabilities.
- Submit one valid creation request.
- Poll the same creation every few seconds.
- Read outputs after ready.
- If paused, show available_actions and wait for the required user action.
- If failed, show the safe reason and let the user revise the request.
- If network state is uncertain, get the existing creation before creating another one.