Import into hizi

Import the files of @hizi.io/engine-generator into a hosted Hizi Engine Config in the hizi app. You do not need the AI creator or Docker. A Hizi Engine Config is the stored game data of a hizi engine game. See What's What in the hizi app.

You can import in two ways:

• In the hizi app, with the Import button of the creator.
• With the hizi API, for a script or a CI job.

Both ways run the same checks and save the game data the same way.

Prerequisites

• Your plan and your user (or API key) have the HIZI_ENGINE_CUSTOM permission. Without it, the import fails with HTTP 403.
• Your user (or API key) has the HIZI_ENGINE_ADMIN permission. This permission lets you change a Hizi Engine Config.
• The config is a Blank / Import config. It has no game type of the creator (such as slot or plinko). The API rejects an import into a creator config with HTTP 422.
• You have the generator output: config.json, entries.jsonl.br and scenarios.jsonl.br. See Output Format.

Package the archive

The import takes one zip archive, game-data.zip. Put the files at the top level of the archive, not in a folder:

game-data.zip
  ├─ config.json
  ├─ entries.jsonl.br
  └─ scenarios.jsonl.br

Make the archive from the output directory of the generator. The -j option stores the files without their folder:

cd output
zip -j ../game-data.zip config.json entries.jsonl.br scenarios.jsonl.br

A builder.json file is optional. A pure generator export does not need one. Add it only when you re-import an archive that you downloaded from the creator. The import then reads the creator settings from it.

Import checks

The import does these checks. If a check fails, the import stops with the message of the check:

Check	Message when the check fails
The archive is a valid zip archive. A gzip-compressed zip archive is also accepted.	The game-data archive is damaged or not a valid zip archive.
config.json is in the archive.	The game-data archive contains no config.json.
config.json and builder.json are at the top level, not in a folder.	game-data.zip must hold config.json and builder.json at its top level, not in a folder (...)
config.json and builder.json (if present) are valid JSON objects.	config.json is not valid JSON. or config.json must contain an object.
The builderType in builder.json (if present) is equal to the gameType in config.json.	The builderType in builder.json does not match the gameType in config.json.
The gameType in config.json is equal to the game type of the config. This applies after the first import.	This archive belongs to a different game type.
The tables in entries.jsonl.br and scenarios.jsonl.br are readable.	The game-data archive could not be read.

The first import sets the game type of the config from gameType in config.json. Every later import into the same config must have the same gameType.

After the checks, hizi saves the game data like the creator does. It makes config.json again, calculates new hashes of the game data, and writes a blank builder.json.

Size limits

Limit	Value
Archive size, import with the API	64 MiB
Entries and settings, unpacked	256 MiB
Archive size, import in the creator	500 MiB
Entries in all tables, without buy-feature tables	500,000
Scenario rows	10,000,000

The limits for entries and scenario rows are the default caps of the generator (maxEntriesPerGame and maxTotalScenarioRows, see API Reference). If you set higher caps in the generator, the import of a larger output fails.

For an archive larger than 64 MiB, import it in the creator in the hizi app.

Import in the hizi app

1. In the hizi app, open Hizi Engine Config.
2. Create a config. Select Blank / Import as the game type.
3. Open the creator of the config.
4. Click Import. Select your game-data.zip.
5. Click Save.

Import with the API

The API is at https://api.hizi.io. Send your tenant API key in the Authorization header as Bearer <your hz_ API key>. Each response has the result in data.

The import has four steps.

1. Read the revision of the config

Call GET /v1/app/foe/{id}. Keep builderRevision from the response. Use 0 if the config has no builderRevision.

curl -s https://api.hizi.io/v1/app/foe/$CONFIG_ID \
  -H "Authorization: Bearer $HIZI_API_KEY" | jq '.data.builderRevision'

2. Upload the archive

Call POST /v1/app/foe/{id}/import/upload?expectedRevision=<builderRevision>. Send the archive as the raw request body, with Content-Type: application/zip.

curl -s https://api.hizi.io/v1/app/foe/$CONFIG_ID/import/upload?expectedRevision=$REVISION \
  -H "Authorization: Bearer $HIZI_API_KEY" \
  -H "Content-Type: application/zip" \
  --data-binary @game-data.zip

The response holds gameDataUploadId, revision and bytes (the number of bytes received). hizi keeps the upload for one day.

3. Start the import

Call POST /v1/app/foe/{id}/import with the revision and the upload ID.

curl -s https://api.hizi.io/v1/app/foe/$CONFIG_ID/import \
  -H "Authorization: Bearer $HIZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"expectedRevision\": $REVISION, \"gameDataUploadId\": \"$UPLOAD_ID\"}"

The call returns a save job at once. Keep its jobId.

4. Wait for the job

Call GET /v1/app/foe/{id}/builder-draft/save/{jobId} until status is succeeded or failed.

curl -s https://api.hizi.io/v1/app/foe/$CONFIG_ID/builder-draft/save/$JOB_ID \
  -H "Authorization: Bearer $HIZI_API_KEY" | jq '.data | {status, phase, error, savedRevision}'

• phase is the step that the job does now.
• error is the message of the failed check when status is failed.
• savedRevision is the new revision of the config after a successful import. Use it as expectedRevision for your next call.

hizi keeps a job for 24 hours. If the server of the config stops during the job, the job fails with the cause in error. Start the import again.

The hizi MCP server has the same import as the import_hizi_engine_config_game_data tool. The upload in step 2 must still use the REST call, because the archive cannot go through MCP.

Errors

HTTP status	Cause	What to do
403	Your plan or your permissions do not include HIZI_ENGINE_CUSTOM or HIZI_ENGINE_ADMIN.	Ask the owner of your tenant for the permissions.
404	The upload expired. hizi keeps an upload for one day.	Upload the archive again.
409	The revision is old. The config changed after you read it.	Read the config again. Send the new builderRevision.
409	A server simulation holds the config read-only, or another save, import or certification bundle of the config runs.	Wait until it finishes. Then try again.
413	The archive is larger than 64 MiB.	Import the archive in the creator in the hizi app.
415	The Content-Type of the upload is not application/zip.	Send the archive as the raw body with Content-Type: application/zip.
422	The config has a game type of the creator.	Create a Blank / Import config. Import into that config.
503	Another creator job runs.	Wait. Then try again.

A failed import check does not return an HTTP error. The job ends with status: failed, and error holds the message. See Import checks.