Projects and batches

Every generation belongs to a project — a named group of related assets. Put everything you generate for a single purpose in one project. Create a project whenever you will generate more than one asset for the same purpose, and pass its project_id on every request. Omit project_id and each POST /api/v1/assets creates its own single-asset project named from your prompt, which is what you want for a one-off and not what you want for a batch.

Omitting project_id across a batch is the most common source of a cluttered project list: twenty generations become twenty single-asset projects, and you cannot merge them afterwards. Decide the grouping before you submit.

Create a project

Create the project up front and retain its project_id.

curl -X POST https://app.moonlakeai.com/api/v1/projects \
  -H "Authorization: Bearer $MOONLAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "warehouse-props"}'

import os

import requests

project = requests.post(
    "https://app.moonlakeai.com/api/v1/projects",
    headers={"Authorization": f"Bearer {os.environ['MOONLAKE_API_KEY']}"},
    json={"name": "warehouse-props"},
).json()
project_id = project["project_id"]

Group without tracking a project id

Retaining a project_id between calls means carrying state — awkward for a script that runs on a schedule, and often skipped entirely by a coding agent that treats each request independently. Send an Idempotency-Key instead and the same key resolves to the same project for as long as that project exists, so every run groups itself with no bookkeeping.

curl -X POST https://app.moonlakeai.com/api/v1/projects \
  -H "Authorization: Bearer $MOONLAKE_API_KEY" \
  -H "Idempotency-Key: warehouse-props-2026-08" \
  -H "Content-Type: application/json" \
  -d '{"name": "warehouse-props August"}'

import os

import requests

response = requests.post(
    "https://app.moonlakeai.com/api/v1/projects",
    headers={
        "Authorization": f"Bearer {os.environ['MOONLAKE_API_KEY']}",
        "Idempotency-Key": "warehouse-props-2026-08",
    },
    json={"name": "warehouse-props August"},
)
project_id = response.json()["project_id"]

The first call creates the project and returns 201. While that project exists, later calls with the key return the same project_id with 200, so you can call it unconditionally at the start of each run and pass the result to POST /api/v1/assets. Deleting the project releases the key: the next call creates a new project and returns 201 again. Choose a key that is stable for everything you want grouped and different for everything you don’t — a release version, a dataset name, or the month. Keys are scoped to your account, so they cannot collide with another customer’s.

The key identifies the project; the name is only a display label used when the project is first created. Renaming a project later does not break the grouping, and reusing a key with a different name returns the existing project unchanged rather than an error.

Generate an asset library

Pass the same project_id with every asset request. This is client-side fan-out: each request produces a different asset and runs independently. The example assumes references is a valid reference list from Generate assets.

python

import os

import requests

prompts = ["wooden pallet", "cardboard box", "steel drum", "hand truck"]
for prompt in prompts:
    requests.post(
        "https://app.moonlakeai.com/api/v1/assets",
        headers={"Authorization": f"Bearer {os.environ['MOONLAKE_API_KEY']}"},
        json={
            "input": {"prompt": prompt, "references": references},
            "project_id": project_id,
            "mode": "generate",
        },
    )

At most 100 generations per account can be pending or processing. Pace a large batch and retry on 429 as earlier generations finish.

Workflow: create project, loop submitting one generation per asset, poll the project for aggregate status, download assets. — Create a project once, fan out one generation per asset, then poll the project for combined progress.

Track the batch

Call GET /api/v1/projects/{project_id} to receive aggregate status counts and up to 1,000 generations. This lets you monitor the batch without polling every asset.

curl

curl https://app.moonlakeai.com/api/v1/projects/{project_id} \
  -H "Authorization: Bearer $MOONLAKE_API_KEY"

{
  "project_id": "…",
  "total": 4,
  "status_counts": { "pending": 1, "processing": 1, "completed": 2, "failed": 0, "cancelled": 0 },
  "generations": [
    { "id": "…", "name": "wooden pallet", "status": "completed" },
    { "id": "…", "name": "cardboard box", "status": "processing" }
  ]
}

For a project with more than 1,000 generations, page through GET /api/v1/assets?project_id={project_id}. Add &status= to filter the list by status.

Get started

Guides

Reference

Create a project

Group without tracking a project id

Generate an asset library

Track the batch

​Create a project

​Group without tracking a project id

​Generate an asset library

​Track the batch

Create a project

Group without tracking a project id

Generate an asset library

Track the batch