SDK, CLI, and REST

Every WorldJen capability is exposed three ways: a REST endpoint, a Python SDK function, and a CLI subcommand. This page lists them side by side so you can pick the surface that fits your workflow.

For per-surface narrative, see Python SDK, CLI, and the REST API.

Score

Get the user's Score session

curl -H "X-API-Key: $WORLDJEN_API_KEY" https://api.worldjen.com/api/v1/score

import worldjen
worldjen.score.get_or_create()

worldjen score get

Reset the Score session

curl -X POST -H "X-API-Key: $WORLDJEN_API_KEY" https://api.worldjen.com/api/v1/score/reset

worldjen.score.reset()

worldjen score reset

Upload and score a clip

# 1. Fetch upload URL
curl -X POST https://api.worldjen.com/api/v1/score/$RUN_ID/videos/upload-url \
  -H "X-API-Key: $WORLDJEN_API_KEY" \
  -d '{"fileName":"clip.mp4","contentType":"video/mp4","prompt":"a cat"}'

# 2. PUT the file to the returned uploadUrl
curl -X PUT --data-binary @clip.mp4 -H "Content-Type: video/mp4" "$UPLOAD_URL"

# 3. Confirm
curl -X POST https://api.worldjen.com/api/v1/score/$RUN_ID/videos/confirm-upload \
  -H "X-API-Key: $WORLDJEN_API_KEY" -d '{"videoId":"VID"}'

worldjen.score.upload("clip.mp4", prompt="a cat", wait=True)

worldjen score upload clip.mp4 --prompt "a cat" --wait

Rank

Get the user's Rank session

curl -H "X-API-Key: $WORLDJEN_API_KEY" https://api.worldjen.com/api/v1/rank

worldjen.rank.get_or_create()

worldjen rank get

Reset the Rank session

curl -X POST -H "X-API-Key: $WORLDJEN_API_KEY" https://api.worldjen.com/api/v1/rank/reset

worldjen.rank.reset()

worldjen rank reset

Upload a candidate

prompt is optional once the session is locked. Passing a different prompt produces a 400 with code: "RANK_PROMPT_MISMATCH". See Rank prompt lock.

curl -X POST https://api.worldjen.com/api/v1/rank/$RUN_ID/videos/upload-url \
  -H "X-API-Key: $WORLDJEN_API_KEY" \
  -d '{"fileName":"variant_a.mp4","contentType":"video/mp4","prompt":"a cat"}'

worldjen.rank.upload("variant_a.mp4", prompt="a cat", wait=True)

worldjen rank upload variant_a.mp4 --prompt "a cat" --wait

Get the leaderboard

curl -H "X-API-Key: $WORLDJEN_API_KEY" https://api.worldjen.com/api/v1/rank/$RUN_ID/ranked

worldjen.rank.get_ranked(run_id)

worldjen rank current

Bench

Create a Bench run

curl -X POST https://api.worldjen.com/api/v1/bench \
  -H "X-API-Key: $WORLDJEN_API_KEY" \
  -d '{"name":"n","dimensions":["aesthetic_quality"],"runner_id":"R","model_id":"M"}'

worldjen.bench.create(
    name="n",
    model_id="M",
    dimensions=["aesthetic_quality"],
    runner_id="R",
)

worldjen bench create --name n --dimensions aesthetic_quality --runner-id R --model-id M

List Bench runs

curl -H "X-API-Key: $WORLDJEN_API_KEY" "https://api.worldjen.com/api/v1/bench?page=1&limit=50"

worldjen.bench.list()

worldjen bench list

Bench resource helpers

Operation	curl	SDK	CLI
Get	GET /api/v1/bench/{id}	worldjen.bench.get(id)	worldjen bench get ID
Cancel	POST /api/v1/bench/{id}/cancel	worldjen.bench.cancel(id)	worldjen bench cancel ID
Delete	DELETE /api/v1/bench/{id}	worldjen.bench.delete(id)	worldjen bench delete ID
Videos	GET /api/v1/bench/{id}/videos	worldjen.bench.videos(id)	worldjen bench videos ID
CSV	GET /api/v1/bench/{id}/csv	worldjen.bench.csv(id)	worldjen bench csv ID -o results.csv
Logs	GET /api/v1/bench/{id}/logs	worldjen.bench.logs(id)	worldjen bench logs ID

Run a pipeline in-process

worldjen.bench.run_with_pipeline(
    my_pipeline,
    dimensions=["subject_consistency"],
    run_name="ltx2-motion-check",
    model_id="MODEL_ID",
)

No CLI equivalent — Python callables don't survive shell arguments. Use Bench's create flow plus a registered runner instead.

Parity matrix

Every capability across curl, Python SDK, CLI, and the auto-generated browser SDK.

Capability	curl	Python SDK	CLI	Browser SDK
Get Score session	GET /api/v1/score	worldjen.score.get_or_create()	worldjen score get	getScoreSession()
Reset Score session	POST /api/v1/score/reset	worldjen.score.reset()	worldjen score reset	resetScoreSession()
Score upload	POST /api/v1/score/{id}/videos/{upload-url,confirm-upload}	worldjen.score.upload(file, ...)	worldjen score upload FILE	uploadScore(file)
Get Rank session	GET /api/v1/rank	worldjen.rank.get_or_create()	worldjen rank get	getRankSession()
Reset Rank session	POST /api/v1/rank/reset	worldjen.rank.reset()	worldjen rank reset	resetRankSession()
Rank upload	POST /api/v1/rank/{id}/videos/{upload-url,confirm-upload}	worldjen.rank.upload(file, ...)	worldjen rank upload FILE	uploadRank(file)
Rank leaderboard	GET /api/v1/rank/{id}/ranked	worldjen.rank.get_ranked(id)	worldjen rank current	getRanked(id)
Create Bench run	POST /api/v1/bench	worldjen.bench.create(...)	worldjen bench create ...	createBench(...)
List Bench runs	GET /api/v1/bench	worldjen.bench.list(...)	worldjen bench list	listBench()
Get Bench run	GET /api/v1/bench/{id}	worldjen.bench.get(id)	worldjen bench get ID	getBench(id)
Cancel Bench run	POST /api/v1/bench/{id}/cancel	worldjen.bench.cancel(id)	worldjen bench cancel ID	cancelBench(id)
Delete Bench run	DELETE /api/v1/bench/{id}	worldjen.bench.delete(id)	worldjen bench delete ID	deleteBench(id)
Bench videos	GET /api/v1/bench/{id}/videos	worldjen.bench.videos(id)	worldjen bench videos ID	benchVideos(id)
Bench CSV	GET /api/v1/bench/{id}/csv	worldjen.bench.csv(id)	worldjen bench csv ID	benchCsv(id)
Bench logs	GET /api/v1/bench/{id}/logs	worldjen.bench.logs(id)	worldjen bench logs ID	benchLogs(id)
Pipeline run	not exposed	worldjen.bench.run_with_pipeline(...)	not exposed (Python callable)	not exposed

Browser SDK function names follow @hey-api/openapi-ts generated from server/openapi.json; consult the generated client for the exact module path.