REST API

Generations API

Retrieve and generate game assets — thumbnails, banners, and promotional images — for your game catalogue.

Authentication

All requests require a Bearer token in the Authorization header. API keys are scoped to your team — you can only access your own games and generations. Requests without a valid key receive a 401 response.

http

Authorization: Bearer YOUR_API_KEY

Base URL

All API requests should be made to the following base URL:

url

https://api.lobbymagic.com

Typical Workflow

Generate assets

Send a POST request with one or more game + preset pairs.

bash

curl -X POST "https://api.lobbymagic.com/v1/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"generations": [{"game_id": "your-game-123", "preset_id": 502}]}'

Wait for completion

Recommended: provide a webhook_url in your request to receive a notification when each generation completes. Alternatively, poll using the generation_id.

bash

# Poll (alternative to webhooks)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lobbymagic.com/v1/generations/51650"

Retrieve all assets for a game

Once complete, use the GET endpoint to list all generated assets for any game.

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lobbymagic.com/v1/generations?game_id=your-game-123"

GET /v1/generations

GET

/v1/generations

Retrieve the latest generated assets for a game. Returns the most recently generated asset per preset and animation type.

Query Parameters

Parameter	Type	Required	Description
game_id	string	Yes	Your external game identifier.
preset_id	integer	No	Filter to a single preset.
animation	boolean	No	Filter by animation type. true = animated only, false = static only.
game_name	string	No	Game title for automatic matching when no manual mapping exists.
provider_name	string	No	Provider name. Improves automatic matching accuracy.
request_id	string	No	Client-supplied identifier echoed back in the response.

Response

json

{
  "status": "ready",
  "reliability": "high",
  "trace_id": "016da67b-...",
  "generations": [
    {
      "generation_id": 20622,
      "preset_id": 372,
      "url": "https://storage.googleapis.com/.../8f27e86f.webp",
      "updated_at": "2025-11-12T05:55:23Z",
      "animation": false,
      "format": "webp",
      "scale": 2,
      "dimensions": { "width": 300, "height": 300 }
    }
  ]
}

Response Status Values

Status	Meaning	Action
ready	Game resolved, assets available.	Use the generations array.
resolved_no_generations	Game resolved, but no assets generated yet.	Use POST to trigger generation.
not_mapped	game_id could not be matched.	Contact Lobby Magic or provide game_name.
ambiguous	Multiple possible matches found.	Contact Lobby Magic with the trace_id.

POST /v1/generations

POST

/v1/generations

Trigger generation of new assets. Accepts one or more game + preset pairs. Returns immediately with generation IDs that you can poll for status.

Request Body

Field	Type	Description
generations	array	Array of game + preset pairs to generate. Each item requires game_id (string) and preset_id (integer). Optional: game_name, provider_name.
request_id	string	Optional client-supplied identifier echoed back in the response.
webhook_url	string	Optional URL to receive a POST notification when each generation completes or fails. See Webhooks section.

Example — Single Game

bash

curl -X POST "https://api.lobbymagic.com/v1/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "generations": [
      {"game_id": "your-game-123", "preset_id": 502}
    ]
  }'

Example — Multiple Games

bash

curl -X POST "https://api.lobbymagic.com/v1/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "generations": [
      {"game_id": "game-1", "preset_id": 502},
      {"game_id": "game-2", "preset_id": 502},
      {"game_id": "game-3", "preset_id": 503}
    ]
  }'

Response (202 Accepted)

json

{
  "batch_id": 9300,
  "generations": [
    {
      "generation_id": 51700,
      "game_id": "game-1",
      "preset_id": 502,
      "status": "pending"
    },
    {
      "generation_id": 51701,
      "game_id": "game-2",
      "preset_id": 502,
      "status": "pending"
    },
    {
      "generation_id": null,
      "game_id": "game-3",
      "preset_id": 503,
      "error": "Game could not be resolved (status: not_mapped)"
    }
  ],
  "trace_id": "6eccfeae-..."
}

Each item in the response is processed independently. If some games fail validation (e.g. not mapped or invalid preset), the valid ones still proceed.

Queued Generations

Games not yet ready for generation will be queued, and then generated automatically once ready. No action is required on your part.

json

{
  "generation_id": 51702,
  "game_id": "new-game",
  "preset_id": 502,
  "status": "queued",
  "message": "This game is awaiting template creation. Your generation will be processed automatically once templates are available."
}

GET /v1/generations/{id}

GET

/v1/generations/{generation_id}

Poll the status of a specific generation. Use the generation_id returned by the POST endpoint.

Response (complete)

json

{
  "generation_id": 51650,
  "status": "complete",
  "preset_id": 502,
  "url": "https://storage.googleapis.com/.../75309786.webp",
  "animation": false,
  "format": "webp",
  "scale": 2,
  "dimensions": { "width": 320, "height": 400 },
  "created_at": "2026-04-02T19:03:25Z",
  "updated_at": "2026-04-02T19:05:47Z"
}

Response (failed)

json

{
  "generation_id": 51650,
  "status": "failed",
  "preset_id": 502,
  "error_message": "Generation failed. Contact support with the generation_id for details.",
  "created_at": "2026-04-02T19:03:25Z",
  "updated_at": "2026-04-02T19:03:27Z"
}

GET /v1/generations/batch/{batch_id}

GET

/v1/generations/batch/{batch_id}

Check the status of all generations in a batch. Use the batch_id returned by the POST endpoint. Useful for tracking progress of multi-game requests without polling each generation individually.

Response

json

{
  "batch_id": 9300,
  "total": 3,
  "queued": 0,
  "pending": 0,
  "processing": 1,
  "complete": 2,
  "failed": 0,
  "generations": [...]
}

Game Resolution

The API resolves your game_id to the Lobby Magic catalogue. There are two resolution methods, reflected in reliability.

Confirmed Mapping (reliability: high)

The Lobby Magic team configures a direct mapping between your game_id and the corresponding game in the catalogue. This is the most reliable method and is returned with reliability: "high".

To set up mappings, provide the Lobby Magic team with a list of your game identifiers and corresponding game titles.

Automatic Matching (reliability: medium)

When no manual mapping exists and you provide game_name (and optionally provider_name), the API attempts to match against the catalogue automatically.

Clear match: The game is resolved automatically with reliability: "medium".
Ambiguous match: Multiple games score similarly. The response returns status: "ambiguous" with reliability: "none".
No match: No game scores above the minimum threshold. Returns status: "not_mapped" with reliability: "none".

Providing provider_name significantly improves matching accuracy, especially for games with common or similar titles across different providers.

Webhooks

Instead of polling, provide a webhook_url in your POST request. When each generation completes or fails, a POST request is sent to your URL.

Example Request with Webhook

bash

curl -X POST "https://api.lobbymagic.com/v1/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "generations": [{"game_id": "game-1", "preset_id": 502}],
    "webhook_url": "https://your-server.com/lobby-magic/callback"
  }'

Webhook Payload (complete)

json

{
  "event": "generation.complete",
  "generation_id": 51700,
  "status": "complete",
  "preset_id": 502,
  "url": "https://storage.googleapis.com/.../image.webp",
  "batch_id": 9300
}

Webhook Payload (failed)

json

{
  "event": "generation.failed",
  "generation_id": 51700,
  "status": "failed",
  "error_message": "Generation failed. Contact support with the generation_id for details.",
  "batch_id": 9300
}

If your server returns a non-2xx response or is unreachable, the webhook is retried up to 3 times with exponential backoff. You can always fall back to polling GET /v1/generations/{id} if webhooks are not received.

Generation Statuses

When you trigger a generation via POST, it progresses through these statuses:

Status	Meaning	Action
queued	Waiting for templates to be created for this game.	No action needed. Poll again later.
pending	Generation accepted, about to start processing.	Poll again in a few seconds.
processing	Scene is being composed and rendered.	Poll again in 10-30 seconds.
complete	Asset is ready. url contains the image URL.	Use the url field.
failed	Generation failed.	Review error_message. Retry with a new POST if appropriate.

Filtering (GET endpoint)

By Preset

To retrieve only a specific preset, pass the preset_id parameter.

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lobbymagic.com/v1/generations?game_id=your-game-123&preset_id=372"

By Animation

To retrieve only animated or static assets, pass the animation parameter.

bash

# Only animated assets
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lobbymagic.com/v1/generations?game_id=your-game-123&animation=true"

# Only static assets
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lobbymagic.com/v1/generations?game_id=your-game-123&animation=false"

Combining Filters

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lobbymagic.com/v1/generations?game_id=your-game-123&preset_id=372&animation=true"

Error Responses

401

Unauthorized

Missing or invalid API key.

json

{
  "detail": "Invalid API key"
}

404

Not Found

Generation or batch not found, or belongs to a different team.

json

{
  "detail": "Generation not found"
}

422

Unprocessable Entity

Missing required fields or invalid values.

json

{
  "detail": "Invalid preset_id. The preset does not exist or does not belong to your team."
}

Usage Notes

Team scoping
You can only access generations belonging to your team. Attempting to access another team's generation returns 404.
One asset per preset and animation type
The GET list endpoint returns the most recently generated asset for each unique combination of preset and animation type.
Queued generations
Games not yet ready for generation will be queued, and then generated automatically once ready. No action required.
Polling interval
For pending/processing generations, poll every 10-30 seconds. Most generations complete within 15-30 seconds.
Multiple games in one request
The POST endpoint accepts an array of game + preset pairs. Each is processed independently — if some fail validation, the valid ones still proceed.
Null fields omitted
Fields with null values are omitted from the response for cleaner payloads.

Support

For mapping requests, integration help, or API issues, contact the Lobby Magic team and include the trace_id or generation_id from the response.