Documentation

POST /v1/images
{
  "model": "kreator-image-pro",
  "prompt": "required non-empty string",
  "ratio": "4:5",
  "resolution": "high",
  "response_format": "url",
  "watermark": false,
  "safety_identifier": "hashed-end-user-id",
  "references": [
    { "type": "image_url", "url": "https://example.com/reference.jpg" }
  ],
  "callback_url": "https://example.com/kreatorflow/webhook",
  "idempotency_key": "optional-body-fallback"
}

POST /v1/characters
{
  "mode": "register",
  "name": "Reference character",
  "upload_id": "tos:kreatorflow/uploads/workspace-id/character-reference.png"
}

Then reuse it:
{
  "model": "kreator-video-seedance-2-fast",
  "prompt": "cinematic scene using the registered character as appearance guidance",
  "character_ids": ["character_id_here"],
  "duration": 5,
  "ratio": "9:16",
  "resolution": "720p"
}

POST /v1/characters prompt mode
{
  "name": "Reference character",
  "prompt": "Create a stylized character portrait using the uploaded reference for hairstyle, wardrobe, pose, style, and color palette.",
  "reference_upload_ids": ["tos:kreatorflow/uploads/workspace-id/character-reference.png"],
  "aspect_ratio": "4:5",
  "resolution": "high"
}

Character reference rules: use a supported image at least 300px wide; outside source-video edit, do not ask to look exactly like, clone, recreate, imitate, replace a face, or match a real person, celebrity, public figure, face, identity, or likeness. If a realistic character request hits "Input text contains sensitive information", person_match_prompt_unsafe, or generation_rejected, remove real-person/celebrity/public-figure/deepfake/impersonation wording, keep the character fictional or authorized, and retry with a new Idempotency-Key.

POST /v1/videos
{
  "model": "kreator-video-seedance-2-fast",
  "content": [
    { "type": "text", "text": "cinematic product reveal, handheld camera" },
    { "type": "image_url", "image_url": "https://example.com/reference.jpg", "role": "first_frame" },
    { "type": "video_url", "video_url": { "url": "https://example.com/reference.mp4" }, "role": "reference_video" },
    { "type": "audio_url", "audio_url": "https://example.com/reference.mp3", "role": "reference_audio" }
  ],
  "duration": 5,
  "ratio": "9:16",
  "resolution": "720p",
  "first_frame_upload_id": "tos:kreatorflow/uploads/workspace-id/first-frame.png",
  "last_frame_upload_id": "tos:kreatorflow/uploads/workspace-id/last-frame.png",
  "generate_audio": true,
  "watermark": false,
  "seed": 12345,
  "video_reference_mode": "strict",
  "callback_url": "https://example.com/kreatorflow/webhook",
  "safety_identifier": "hashed-end-user-id",
  "idempotency_key": "optional-body-fallback"
}

POST /v1/video-edits
{
  "model": "kreator-video-pro",
  "edit_mode": "transform",
  "source_video_upload_id": "tos:kreatorflow/uploads/workspace-id/source-video.mp4",
  "prompt": "please edit my face from the reference_images onto the subject in the video",
  "duration": 5,
  "ratio": "adaptive",
  "resolution": "720p",
  "reference_image_upload_ids": ["tos:kreatorflow/uploads/workspace-id/owned-face-reference.png"]
}

POST /v1/video-edits public URL source
{
  "model": "kreator-video-pro",
  "edit_mode": "transform",
  "video": "https://example.com/source-video.mp4",
  "prompt": "Change the time to a rainy night and use the reference image as authorized appearance guidance.",
  "reference_images": ["https://example.com/authorized-face-reference.jpg"],
  "reference_audios": [],
  "resolution": "720p",
  "generate_audio": true
}

Video reference rules: image references can guide characters, products, frames, style, and composition. video_url and reference_video_upload_ids guide the new video from a clip. For source-video edit, use source_video_upload_id or video/source_video_url on /v1/video-edits or /v1/videos with intent=video_edit. Edit jobs force strict source-video handling, default to ratio=adaptive when no ratio is sent, and release reserved tokens on KreatorFlow failure. An owned source clip must be a same-workspace VIDEO upload created with upload_type VIDEO; image/audio upload ids are rejected before billing. A public video/source_video_url is fetched safely and normalized through KreatorFlow video storage first, then tried directly; if direct source submit is rejected before task creation, KreatorFlow retries once with the prepared source registered internally. Public reference_images can be sent directly for one-off authorized appearance guidance; /v1/characters is optional for reusable character ids only. Source clips should be MP4/MOV with H.264/AAC under 50 MB. Owned/authorized face or appearance edit wording can dispatch, including "please edit my face from the reference_images onto the subject in the video"; celebrity, public-figure, deepfake, and impersonation wording returns person_match_prompt_unsafe. reference_asset_failed means internal source/reference preparation, registration, pending review, or review failed and reserved tokens were released. Normal video references do not guarantee person, character, or face replacement inside an existing source video. If a normal video clip reference fails during reference preparation, submit, or polling time, default fallback retries once without video clip references and returns a video_reference_fallback_omitted_clips warning. Use video_reference_mode=strict when the driving clip must not be omitted.

Use /api/kreator/developers/docs.json for machine-readable integration data.

Base URL: https://kreatorflow.ai
Auth: Authorization: Bearer $KREATORFLOW_API_KEY
JSON docs: /api/kreator/developers/docs.json
Models: GET /v1/models
Images: POST /v1/images
Characters: POST/GET /v1/characters and GET/DELETE /v1/characters/{character_id}
Videos: POST /v1/videos
Video edits: POST /v1/video-edits
Jobs: GET /v1/jobs/{job_id}
Billing: /development?section=billing for Stripe token top-ups
Stripe webhooks: required to post paid top-ups
Developer job webhooks: live terminal callbacks through webhook_url/callback_url; keep polling as fallback
Output storage: completed jobs return a KreatorFlow-authenticated providerOutputUrl backed by output delivery; developers fetch with their API key and store outputs in their own storage
Current generation status: dispatch is wired and may return dispatch_disabled when live API generation is disabled in the environment
Video dispatch: /v1/videos and /v1/video-edits attempt KreatorFlow dispatch before the create response returns, so successful video creates should return either a processing/completed job or a terminal failed job with tokens released
Video stall recovery: if a video/V2V job still stays processing before dispatch starts, stale repair fails it as generation_timeout and releases reserved tokens instead of leaving it stuck forever
Reusable characters: use POST /v1/uploads, PUT the image bytes, then POST /v1/characters with mode=register and an owned upload_id. Store data.character.character_id and pass it as character_ids on /v1/images or /v1/videos.
Character references: one-off POST /v1/characters prompt-mode jobs still accept owned upload_id references; use normal images at least 300px wide and avoid person/celebrity/likeness matching wording
Sensitive-text recovery: if a realistic character request hits "Input text contains sensitive information", generation_rejected, character_prompt_unsafe, or person_match_prompt_unsafe, register the owned reference with /v1/characters mode=register, remove real-person/celebrity/public-figure/deepfake/impersonation/exact-identity wording, keep the character fictional or authorized, and retry with a new Idempotency-Key
Video references: video_url and reference_video_upload_ids are clip guidance for /v1/videos, not a set-character-replace, identity-swap, or face-swap endpoint for an existing video
Public reference URLs: use reference_image_urls/referenceImageUrls/reference_images for image references, reference_video_urls/referenceVideoUrls/reference_videos for normal clip guidance, reference_audio_urls/referenceAudioUrls/reference_audios for audio references, or put public URLs in content/references arrays. These fields are parsed into real references, not ignored metadata.
Video edits: for source-video transform/restyle/extend, either upload the source video through /v1/uploads with upload_type VIDEO and send source_video_upload_id, or send a public HTTPS source URL in video/source_video_url; image/audio upload ids are rejected before billing; edit jobs force strict source-video handling and release reserved tokens on KreatorFlow failure
Source-video edits: the source clip can be an owned VIDEO upload from the same developer workspace or a public HTTPS video/source_video_url. Public reference_images can be sent directly for one-off authorized identity, appearance, style, wardrobe, product, or composition guidance; /v1/characters is only needed for reusable character ids. MP4/MOV with H.264/AAC under 50 MB is recommended. Source-video edits default to ratio=adaptive when no ratio is sent, so vertical clips keep their framing. KreatorFlow normalizes source clips through KreatorFlow video storage before edit dispatch, then tries the prepared source after ownership checks or safe external fetch; if direct source submit is rejected before task creation, KreatorFlow retries once with the prepared source registered internally. Owned/authorized face or appearance edit wording can dispatch, including "please edit my face from the reference_images onto the subject in the video"; celebrity, public-figure, deepfake, and impersonation wording returns person_match_prompt_unsafe before dispatch. Internal source/reference preparation, registration, pending review, or review failures return reference_asset_failed and release reserved tokens
Video first/last frames: upload image bytes with POST/PUT /v1/uploads, then send first_frame_upload_id and last_frame_upload_id on /v1/videos; generic reference_image_upload_ids remain appearance/style references
Video reference fallback: by default, if a video clip reference fails during reference preparation, submit, or polling time, KreatorFlow retries once without video clip references, returns a video_reference_fallback_omitted_clips warning, and records the fallback in admin diagnostics
Strict driving clips: set video_reference_mode=strict when the driving clip must not be omitted; strict jobs fail and release reserved tokens instead of returning a no-clip fallback, including if KreatorFlow dispatch stalls before the job starts