Developer API

Quick start

Create an API key, submit your first video, and download the result.

Create a test key in the developer console, then make a request from your server. Test mode simulates a video job without calling paid generation providers. Its sample output is a fixture, not a video made from your script.

Create a key with videos:write, videos:read, and assets:read.
Set KINEMA_API_BASE to https://app.kinema.cc/v1. All examples also use KINEMA_API_KEY for your test key and VIDEO_REQUEST_ID for a unique ID you save for this video and reuse for retries.
Submit the request. Save the returned video ID and your idempotency key.
Poll for completion or receive a webhook. Retrieve the download link once completed.

cURL

# Set these in your shell. Start with a test key.
export KINEMA_API_BASE="https://app.kinema.cc/v1"
export KINEMA_API_KEY="YOUR_TEST_KEY"

# List available voices. The sandbox fixture below uses test_voice.
curl --fail-with-body "$KINEMA_API_BASE/voices" \
  -H "Authorization: Bearer $KINEMA_API_KEY"

# Choose one ID per intended video. Reuse it if this request needs retrying.
export VIDEO_REQUEST_ID="quickstart-video-001"

curl --fail-with-body "$KINEMA_API_BASE/videos" \
  -H "Authorization: Bearer $KINEMA_API_KEY" \
  -H "Idempotency-Key: $VIDEO_REQUEST_ID" \
  -H "Content-Type: application/json" \
  --data '{
  "title": "My first Kinema video",
  "script": "Every great story begins with a question. What will you create next? Start with a moment that matters, follow the details that make it memorable, and bring your audience somewhere new. With a clear idea and a little curiosity, an ordinary story can become something worth sharing.",
  "voice": {
    "id": "test_voice"
  },
  "output_mode": "video",
  "production_mode": "standard",
  "language": "en",
  "music": true,
  "graphics": true,
  "captions": true
}'

# Copy the returned id, then check progress.
curl --fail-with-body "$KINEMA_API_BASE/videos/VIDEO_ID" \
  -H "Authorization: Bearer $KINEMA_API_KEY"

# When status is completed, retrieve the download response.
curl --fail-with-body "$KINEMA_API_BASE/videos/VIDEO_ID/download" \
  -H "Authorization: Bearer $KINEMA_API_KEY"

These examples use the sandbox’s test_voice fixture. For live requests, choose a real voice_id from GET /voices and replace it in the request. Live videos must meet the validation and duration limits shown in the API response.