Qiklab API Documentation

Get your profile and balance.

Example Request

curl https://www.qiklab.com/api/v1/me \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}"

Response

{
  "username": "johndoe",
  "email": "john@example.com",
  "bio": "AI enthusiast",
  "location": "San Francisco, CA",
  "balance_cents": 999,
  "balance_dollars": "9.99",
  "created_at": "2026-03-15T12:00:00+00:00"
}

Start a generation job.

Request Body (JSON)

Example Request (t2i)

Text-to-Image generates 4 images per request. The status response will include a result_urls array with all 4 image URLs.

curl -X POST https://www.qiklab.com/api/v1/generate \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "t2i",
    "positive_prompt": "A beautiful sunset over the ocean",
    "aspect_ratio": "3:2"
  }'

Example Request (i2i)

curl -X POST https://www.qiklab.com/api/v1/generate \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "i2i",
    "positive_prompt": "Oil painting style, warm sunset tones",
    "negative_prompt": "blurry, low quality",
    "resolution": "1k",
    "orientation": "square",
    "image": "data:image/png;base64,iVBORw0KGgo..."
  }'

Example Request (t2i_pro)

curl -X POST https://www.qiklab.com/api/v1/generate \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "t2i_pro",
    "positive_prompt": "A photorealistic portrait, studio lighting",
    "aspect_ratio": "2:3",
    "resolution": "2k",
    "background": "auto"
  }'

Example Request (t2v)

duration accepts any integer from 6 to 30 (default 6). aspect_ratio is required. negative_prompt is not supported on this mode and will be rejected with 400.

curl -X POST https://www.qiklab.com/api/v1/generate \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "t2v",
    "positive_prompt": "A drone shot flying over a mountain range",
    "resolution": "480p",
    "aspect_ratio": "16:9",
    "duration": 6
  }'

Example Request (t2v_pro)

resolution is 480P, 720P (default) or 1080P. duration accepts any integer from 6 to 30 (default 6). generate_audio (default true) gives the video its own soundtrack; set it to false for a silent video. negative_prompt and audio_upload_id are not supported on this mode and will be rejected with 400.

curl -X POST https://www.qiklab.com/api/v1/generate \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "t2v_pro",
    "positive_prompt": "Cinematic slow-motion waves crashing on rocks",
    "resolution": "720P",
    "aspect_ratio": "16:9",
    "duration": 10,
    "generate_audio": true
  }'

Example Request (i2v)

images is required (1–7 entries; URLs or base64). aspect_ratio is required. duration accepts any integer 6–30 (default 6). negative_prompt, image (singular), and last_frame_url are not supported on this mode and will be rejected with 400.

curl -X POST https://www.qiklab.com/api/v1/generate \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "i2v",
    "positive_prompt": "A bird takes flight from the branch",
    "resolution": "480p",
    "aspect_ratio": "16:9",
    "duration": 6,
    "images": [
      "https://example.com/bird-on-branch.jpg"
    ]
  }'

Example Request (i2v_pro)

Same payload shape as i2v; image accepts URL or base64. duration accepts any integer 2–15. audio_upload_id (driving audio) and clip_upload_id (first clip) are optional — see the upload helpers below.

curl -X POST https://www.qiklab.com/api/v1/generate \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "i2v_pro",
    "positive_prompt": "Camera slowly zooms in, cinematic motion",
    "negative_prompt": "static, low resolution",
    "resolution": "720p",
    "duration": 8,
    "image": "https://example.com/scene.jpg",
    "clip_upload_id": "qiklabclp_eyJ1aWQiOiIuLi4ifQ.AbCdEf...",
    "audio_upload_id": "qiklabaud_eyJ1aWQiOiIuLi4ifQ.GhIjKl..."
  }'

Example Request (motion)

Motion requires a two-step flow: first upload the reference image and reference video via the helpers below, then pass the two returned upload_id values here. Duration (and therefore pricing) is derived from the uploaded video — no duration field is accepted.

curl -X POST https://www.qiklab.com/api/v1/generate \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "motion",
    "positive_prompt": "The character dances gracefully",
    "motion_image_upload_id": "qiklabimg_eyJ1aWQiOiIuLi4ifQ.AbCdEf...",
    "motion_video_upload_id": "qiklabvid_eyJ1aWQiOiIuLi4ifQ.GhIjKl...",
    "resolution": "720p"
  }'

Example Request (mm2v / Compose — Multimodal Reference)

Compose accepts text alone or any combination of image / video / audio reference inputs. Pick a scenario first — text_only, first_frame, first_and_last_frame, or multimodal_reference — and only the slots valid for that scenario are accepted. Inline reference tagging (@imageN, @audioN, @videoN) is supported in multimodal_reference.

curl -X POST https://www.qiklab.com/api/v1/generate \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "mm2v",
    "scenario": "multimodal_reference",
    "positive_prompt": "Combine @image1 with @video1 and overlay @audio1 — cinematic slow-motion",
    "aspect_ratio": "adaptive",
    "resolution": "720p",
    "duration": 8,
    "generate_audio": false,
    "compose_image_upload_ids": ["qiklabcmpi_..."],
    "compose_video_upload_ids": ["qiklabcmpv_..."],
    "compose_audio_upload_ids": ["qiklabcmpa_..."]
  }'

Example Request (mm2v / Compose — Text Only)

Text Only scenario: no input slots needed, just a prompt + scenario + the standard video controls. generate_audio defaults to true and adds a +$0.05 surcharge to the per-second rate.

curl -X POST https://www.qiklab.com/api/v1/generate \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "mm2v",
    "scenario": "text_only",
    "positive_prompt": "A cinematic wide shot of a sailboat at sunset, slow camera dolly",
    "aspect_ratio": "21:9",
    "resolution": "1080p",
    "duration": 12,
    "generate_audio": true
  }'

Example Request (i2i_pro with URLs)

The images field accepts URLs or base64 strings (with or without data:image/png;base64, prefix). Base64 images are automatically uploaded and converted server-side.

curl -X POST https://www.qiklab.com/api/v1/generate \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "i2i_pro",
    "positive_prompt": "Recreate me perfectly in this pose",
    "resolution": "1k",
    "aspect_ratio": "3:4",
    "images": [
      "https://your-storage.com/photo1.jpg",
      "https://your-storage.com/photo2.jpg"
    ]
  }'

Example Request (i2i_pro with base64)

curl -X POST https://www.qiklab.com/api/v1/generate \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "i2i_pro",
    "positive_prompt": "Recreate me perfectly in this pose",
    "resolution": "1k",
    "aspect_ratio": "3:4",
    "images": [
      "data:image/png;base64,iVBORw0KGgo...",
      "/9j/4AAQSkZJRg..."
    ]
  }'

Both data:image/...;base64, prefixed and raw base64 strings are accepted. You can also mix URLs and base64 in the same request.

Example Request (i2i_pro_plus)

Pro+ variant uses a higher-quality model. Same parameters as i2i_pro but with mode: "i2i_pro_plus". Pricing: 1K = $0.20, 2K = $0.25, 4K = $0.30.

curl -X POST https://www.qiklab.com/api/v1/generate \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "i2i_pro_plus",
    "positive_prompt": "Recreate me perfectly in this pose",
    "resolution": "2k",
    "aspect_ratio": "3:4",
    "images": [
      "https://your-storage.com/photo1.jpg",
      "https://your-storage.com/photo2.jpg"
    ]
  }'

Example Request (i2i_pro_plus with base64)

curl -X POST https://www.qiklab.com/api/v1/generate \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "i2i_pro_plus",
    "positive_prompt": "Recreate me perfectly in this pose",
    "resolution": "2k",
    "aspect_ratio": "3:4",
    "images": [
      "data:image/png;base64,iVBORw0KGgo...",
      "/9j/4AAQSkZJRg..."
    ]
  }'

Both data:image/...;base64, prefixed and raw base64 strings are accepted. You can also mix URLs and base64 in the same request.

Response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "QUEUED",
  "kind": "Image"
}

kind is one of Image, Video, or Audio — derived from the request mode. Use it to decide how to render the eventual result_url.

Upload a reference image for motion mode. Returns a signed upload handle.

Motion is a two-step flow. First upload the reference image and reference video through these helpers; both endpoints return an upload_id that you pass back to POST /api/v1/generate with mode=motion. Handles are valid for 24 hours.

Request Body (multipart/form-data)

Example Request

curl -X POST https://www.qiklab.com/api/v1/uploads/motion/image \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}" \
  -F "file=@/path/to/reference.jpg"

Response

{
  "status": "success",
  "data": {
    "upload_id": "qiklabimg_eyJ1aWQiOiIuLi4ifQ.AbCdEf...",
    "expires_at": "2026-04-18T17:00:00Z",
    "width": 1024,
    "height": 1024,
    "size_bytes": 845221
  }
}

Upload a reference video for motion mode. Returns a signed upload handle with duration.

Request Body (multipart/form-data)

The video's duration drives motion pricing and is baked into the signed upload handle — you don't need to pass it back separately.

Example Request

curl -X POST https://www.qiklab.com/api/v1/uploads/motion/video \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}" \
  -F "file=@/path/to/reference.mp4"

Response

{
  "status": "success",
  "data": {
    "upload_id": "qiklabvid_eyJ1aWQiOiIuLi4ifQ.GhIjKl...",
    "expires_at": "2026-04-18T17:00:00Z",
    "duration_seconds": 8,
    "width": 1920,
    "height": 1080,
    "size_bytes": 34215441
  }
}

Upload an audio file for use as an i2v_pro driving-audio input. Returns a signed upload handle.

Request Body (multipart/form-data)

The returned upload_id is passed back to POST /api/v1/generate as audio_upload_id for mode=i2v_pro (forwarded as driving_audio_url). Handles are valid for 24 hours.

Example Request

curl -X POST https://www.qiklab.com/api/v1/uploads/t2v/audio \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}" \
  -F "file=@/path/to/track.mp3"

Response

{
  "status": "success",
  "data": {
    "upload_id": "qiklabaud_eyJ1aWQiOiIuLi4ifQ.AbCdEf...",
    "expires_at": "2026-04-26T17:00:00Z",
    "size_bytes": 4823104,
    "content_type": "audio/mpeg"
  }
}

Upload a short video clip for use as an i2v_pro first-clip input. Returns a signed upload handle.

Request Body (multipart/form-data)

The returned upload_id is passed back to POST /api/v1/generate as clip_upload_id for mode=i2v_pro. The upstream model continues motion from the supplied clip (forwarded as first_clip_url). Handles are valid for 24 hours.

Example Request

curl -X POST https://www.qiklab.com/api/v1/uploads/i2v/clip \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}" \
  -F "file=@/path/to/clip.mp4"

Response

{
  "status": "success",
  "data": {
    "upload_id": "qiklabclp_eyJ1aWQiOiIuLi4ifQ.AbCdEf...",
    "expires_at": "2026-04-27T17:00:00Z",
    "size_bytes": 12582912,
    "content_type": "video/mp4"
  }
}

Upload one reference image for Compose / mm2v. Returns a signed upload handle.

Request Body (multipart/form-data)

Pass back as one entry in compose_image_upload_ids (array, 1..30) on POST /api/v1/generate with mode=mm2v, scenario=multimodal_reference. Index in the array maps to the @imageN tag in the prompt (1-indexed).

Upload one reference video for Compose / mm2v. Returns a signed upload handle with duration.

Request Body (multipart/form-data)

Pass back in compose_video_upload_ids (array, 1..10). Combined duration across the array is capped at 30 seconds (re-summed at /generate time from the signed handles — tampering rejected).

Upload one reference audio file for Compose / mm2v. Returns a signed upload handle with duration.

Request Body (multipart/form-data)

Pass back in compose_audio_upload_ids (array, 1..10). Combined duration across the array is capped at 30 seconds. Audio without an image or video reference in the same request is rejected.

Upload the first-frame image for Compose. Returns a signed upload handle.

Request Body (multipart/form-data)

Pass back as compose_first_frame_upload_id on POST /api/v1/generate with scenario=first_frame or first_and_last_frame.

Upload the last-frame image for Compose (first_and_last_frame scenario only). Returns a signed upload handle.

Request Body (multipart/form-data)

Pass back as compose_last_frame_upload_id on POST /api/v1/generate with scenario=first_and_last_frame.

Check the status of a generation job.

Path Parameters

Example Request

curl https://www.qiklab.com/api/v1/status/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}"

Response (in progress)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "IN_PROGRESS"
}

Response (processing)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PROCESSING"
}

PROCESSING means the generation is done but the result is being prepared. Continue polling.

Response (completed)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "COMPLETED",
  "result_url": "https://...",
  "expires_at": 1738128502
}

result_url is a time-limited signed URL. expires_at is the Unix epoch (seconds, UTC) when the signature stops working — safe to cache the URL until then. Download the file before then.

Response (failed)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "FAILED",
  "error": "Generation failed"
}

Check your current account balance.

Example Request

curl https://www.qiklab.com/api/v1/balance \
  -H "Authorization: Bearer qkapi_{replace-with-your-api-key-here}"

Response

{
  "balance_cents": 999,
  "balance_dollars": "9.99"
}