Getting started

Type: Tutorial · Time: 15 minutes Goal: Create an API key and make your first authenticated request.

The KinoCloud API lets you submit render and simulation jobs, poll status, fetch outputs, and manage credits from any script, CI pipeline, or AI agent — without opening a browser.

Base URL: https://app.kinocloud.io/api/v1

---

Step 1 — Create an API key

Sign in to app.kinocloud.io, open Settings → API Keys, and click Create key.

Give it a name (e.g. my-pipeline), select live environment, and choose the scopes you need:

Scope	What it allows
jobs:read	List jobs, get status, get outputs
jobs:write	Submit, cancel, resume jobs; presign uploads
credits:read	Read credit balance and ledger

Copy the key — it starts with kc_live_ and is shown once.

---

Step 2 — Verify the key

curl https://app.kinocloud.io/api/v1/credits/balance \
  -H "Authorization: Bearer kc_live_YOUR_KEY_HERE"

Expected response:

{
  "total_credited_cents": 5000,
  "held_cents": 0,
  "available_cents": 5000,
  "available_display": "$50.00"
}

If you see 401 Unauthorized double-check the Authorization header format — it must be Bearer (with a space) followed by the key.

---

Step 3 — Get a cost estimate

Before submitting a job, price it first:

curl -X POST https://app.kinocloud.io/api/v1/jobs/estimate \
  -H "Authorization: Bearer kc_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "jobType": "render",
    "frameStart": 1,
    "frameEnd": 100,
    "metadata": { "software": "blender", "renderer": "cycles" }
  }'

Response:

{
  "estimatedCost": 0.42,
  "currency": "USD",
  "hasLicenseFee": false,
  "breakdown": {
    "compute": 0.38,
    "software": 0.00,
    "storage": 0.02,
    "egress": 0.02,
    "startFee": 0.00
  }
}

---

Step 4 — Upload a scene file

# 1. Presign an upload URL
curl -X POST https://app.kinocloud.io/api/v1/jobs/upload-url \
  -H "Authorization: Bearer kc_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "scene.blend",
    "contentType": "application/x-blend",
    "size": 10485760
  }'

Response gives you uploadUrl and s3Key. Upload directly:

# 2. PUT the file to the presigned URL (no auth header needed here)
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/x-blend" \
  --upload-file scene.blend

---

Step 5 — Submit the job

curl -X POST https://app.kinocloud.io/api/v1/jobs/submit \
  -H "Authorization: Bearer kc_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "jobType": "render",
    "sceneFile": "YOUR_S3_KEY_FROM_STEP_4",
    "frameStart": 1,
    "frameEnd": 100,
    "outputFormat": "EXR",
    "jobName": "my-first-job"
  }'

Response:

{
  "jobId": "job_01JABCDE12345",
  "status": "SUBMITTED",
  "estimatedCost": 0.42,
  "currency": "USD",
  "provider": "aws-deadline",
  "message": "Job submitted successfully"
}

---

Step 6 — Poll status and fetch outputs

# Poll until status is SUCCEEDED
curl https://app.kinocloud.io/api/v1/jobs/job_01JABCDE12345/status \
  -H "Authorization: Bearer kc_live_YOUR_KEY_HERE"

# Once SUCCEEDED, get presigned download URLs
curl https://app.kinocloud.io/api/v1/jobs/job_01JABCDE12345/outputs \
  -H "Authorization: Bearer kc_live_YOUR_KEY_HERE"

---

Currency & units

A few money fields are worth calling out so reconciliation is unambiguous:

Field	Unit
estimatedCost (estimate / submit)	Whole currency units in currency (e.g. USD 0.42 = $0.42)
available_cents, held_cents, total_credited_cents (balance)	USD cents (5000 = $50.00)
available_display	Pre-formatted USD string, e.g. "$50.00"

Note: Credit top-ups are charged in GBP at the Stripe checkout, while estimates and balances are denominated in USD. If you reconcile spend across both, convert using the rate at time of purchase — don't assume a 1:1 mapping between the amount charged and credits granted.

---

Next steps

• Authentication & API keys — scopes, test keys, rotation
• Submitting jobs — render vs simulation, idempotency
• MCP setup — let AI agents drive KinoCloud
• Errors & rate limits — error codes, limits, headers
• Versioning & deprecation — change policy and lifecycle
• Interactive reference — full endpoint docs with Try-it panel