Nomiq Python SDK — Complete Installation and Usage Guide

The nomiq-python package is the official SDK for integrating Nomiq’s AI brand generation engine into Python applications. It provides a clean, synchronous client interface over the Nomiq REST API, handles bearer token authentication on every request, and includes a built-in HMAC verification helper for securing your webhook endpoints — everything you need to go from install to your first generated brand identity in minutes.

Requirements

Before installing the SDK, confirm your environment meets the minimum version requirement:

Python 3.9 or higher — the SDK uses type hints and language features introduced in Python 3.9.

Install the SDK

Install nomiq-python from PyPI using your preferred package manager.

pip install nomiq-python

pip3 install nomiq-python

uv add nomiq-python

Never hardcode your API key directly in your source files or commit it to version control. Always load secrets from environment variables or a secrets manager such as AWS Secrets Manager or HashiCorp Vault.

Initialize the Client

Import the nomiq module and instantiate a Client by passing your API key. The client is the single entry point for all SDK methods and authenticates every request automatically.

import os
import nomiq

client = nomiq.Client(api_key=os.environ['NOMIQ_API_KEY'])

The Client attaches your key as a Bearer token on the Authorization header for every outbound request to https://api.nomiq.com/v1. For local development, use a .env file with a library such as python-dotenv to load NOMIQ_API_KEY into your environment before your script runs.

Create a Project

Projects are the top-level containers for all brand assets and generation history. You must create a project before you can dispatch a generation job.

project = client.projects.create(
    name='Acme Corp Rebrand',
    description='Enterprise software client — Q3 rebrand initiative.',
)

print(project.id)   # "proj_1A2b3C4d5E"
print(project.name) # "Acme Corp Rebrand"

A successful response returns a project object you can immediately use:

{
  "id": "proj_1A2b3C4d5E",
  "object": "project",
  "name": "Acme Corp Rebrand",
  "description": "Enterprise software client — Q3 rebrand initiative.",
  "created_at": 1677649420,
  "metadata": {}
}

Generate a Brand

Call client.brands.generate() with your project_id and a detailed semantic prompt. Generation runs asynchronously — you receive a 202 Accepted response with a job object immediately, and the completed assets are delivered to your webhook URL when the AI Engine finishes.

job = client.brands.generate(
    project_id='proj_1A2b3C4d5E',
    prompt=(
        'A modern coffee shop in Brooklyn specializing in cold brew. '
        'The logo should feature a minimalistic cold brew glass with a '
        'deep indigo and cream color palette. Typography should be a '
        'clean sans-serif.'
    ),
)

print(job.status) # "queued"
print(job.id)     # "job_9x8y7z6w"

The returned job object confirms the request is in the queue:

{
  "object": "job",
  "id": "job_9x8y7z6w",
  "project_id": "proj_1A2b3C4d5E",
  "status": "queued",
  "created_at": 1677649420
}

Handle the Webhook

Configure your webhook endpoint URL in Workspace Settings and listen for generation.success or generation.failed events. Nomiq signs every webhook request with an HMAC-SHA256 signature in the Nomiq-Signature header — you must verify this before processing any payload.The example below shows a complete Flask webhook handler using Python’s built-in hmac module for constant-time signature comparison.

import os
import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = os.environ['NOMIQ_WEBHOOK_SECRET']

@app.route('/webhook/nomiq', methods=['POST'])
def nomiq_webhook():
    raw_body = request.get_data()
    incoming_sig = request.headers.get('Nomiq-Signature', '')

    # Compute the expected HMAC-SHA256 signature
    expected_sig = hmac.new(
        WEBHOOK_SECRET.encode('utf-8'),
        raw_body,
        hashlib.sha256,
    ).hexdigest()

    # Use compare_digest to prevent timing attacks
    if not hmac.compare_digest(expected_sig, incoming_sig):
        return jsonify(error='Invalid signature.'), 400

    event = request.get_json()

    if event['type'] == 'generation.success':
        job_id = event['data']['job_id']
        project_id = event['data']['project_id']
        assets = event['data']['assets']

        print(f'Job {job_id} complete for project {project_id}')
        print('Logo SVG:', assets['logo_svg'])
        print('Primary color:', assets['primary_color'])
        print('Font family:', assets['font_family'])

        # Queue further processing asynchronously; do not block this handler.

    elif event['type'] == 'generation.failed':
        print(f"Job {event['data']['job_id']} failed:", event['data']['error']['message'])

    # Return 200 immediately to acknowledge receipt.
    return jsonify(success=True), 200

if __name__ == '__main__':
    app.run(port=3000)

Projects

The client.projects namespace exposes the full Projects API, letting you create and manage project containers programmatically.

Create a Project

project = client.projects.create(
    name='Velocity Fitness App',
    description='Brand identity for a B2C fitness tracking startup.',
)

print(project.id) # "proj_1A2b3C4d5E"

Retrieve a Project

Fetch the current state of any existing project by its ID.

project = client.projects.retrieve('proj_1A2b3C4d5E')

print(project.name)       # "Velocity Fitness App"
print(project.created_at) # 1677649420

List Projects

Returns all projects in your workspace sorted newest-first. The response supports cursor-based pagination via limit and starting_after.

response = client.projects.list(limit=20)

for project in response.data:
    print(f'{project.id}: {project.name}')

# Paginate to the next page using the last item's ID as the cursor.
if response.data:
    next_page = client.projects.list(
        limit=20,
        starting_after=response.data[-1].id,
    )

Delete a Project

client.projects.delete('proj_1A2b3C4d5E')

Deleting a project is permanent and irreversible. All associated generated assets, history nodes, and memory data are immediately removed from the database. This action cannot be undone.

Brand Generation

Dispatch a brand generation job by providing a project_id and a rich semantic prompt. You can optionally pass a webhook_url to override the default delivery endpoint configured in your Workspace Settings on a per-request basis.

job = client.brands.generate(
    project_id='proj_1A2b3C4d5E',
    prompt=(
        'A boutique law firm in Chicago focused on intellectual property. '
        'Professional and authoritative tone. Navy blue and gold color '
        'palette with a classic serif typeface.'
    ),
    webhook_url='https://your-app.com/webhooks/nomiq',  # optional override
)

print(job.id)     # "job_9x8y7z6w"
print(job.status) # "queued"

Generation jobs typically complete within 3–10 seconds depending on asset complexity. Do not poll the API for status — Nomiq will POST the completed assets to your webhook endpoint automatically.

Handling Webhooks

Nomiq delivers the completed brand assets via a POST request to your configured webhook URL. The full generation.success payload contains the SVG markup, primary color hex value, and font family:

{
  "event_id": "evt_5k6l7m8n",
  "type": "generation.success",
  "created_at": 1677649428,
  "data": {
    "job_id": "job_9x8y7z6w",
    "project_id": "proj_1A2b3C4d5E",
    "memory_id": "mem_X1y2Z3w4",
    "assets": {
      "logo_svg": "<svg>...</svg>",
      "primary_color": "#4f46e5",
      "font_family": "Inter"
    }
  }
}

The memory_id field identifies the Memory Node created for this generation. Store it alongside your job record — pass it back to client.brands.generate() as the memory_id parameter to refine this brand in a subsequent iteration rather than generating from scratch. Return a 200 OK response within 5 seconds of receiving the webhook. Offload any heavy work — database writes, file storage, downstream notifications — to an asynchronous task queue such as Celery or RQ. If Nomiq does not receive a 200 within the timeout window, it retries with exponential backoff.

Error Handling

The SDK raises structured exceptions when the API returns a non-2xx response. Wrap your calls in try/except and inspect the exception’s attributes to implement granular error handling.

import os
import nomiq
from nomiq.errors import NomiqAPIError

client = nomiq.Client(api_key=os.environ['NOMIQ_API_KEY'])

def safe_generate(project_id: str, prompt: str):
    try:
        job = client.brands.generate(
            project_id=project_id,
            prompt=prompt,
        )
        return job
    except NomiqAPIError as e:
        if e.code == 'authentication_error':
            print('Invalid API key. Check your NOMIQ_API_KEY environment variable.')
        elif e.code == 'rate_limit_exceeded':
            print(f'Rate limit exceeded. Retry after {e.retry_after} seconds.')
        elif e.code == 'invalid_project':
            print(f'Project not found: {project_id}')
        else:
            print(f'Nomiq API error [{e.code}]: {e.message}')
        return None
    except Exception as e:
        # Re-raise unexpected network or runtime errors
        raise

The NomiqAPIError exception exposes the following attributes for structured handling:

Attribute	Type	Description
`code`	`str`	Machine-readable error code (e.g., `rate_limit_exceeded`).
`message`	`str`	Human-readable description of the error.
`status`	`int`	The HTTP status code returned by the API.
`retry_after`	`int \| None`	Seconds to wait before retrying (set on `429` responses).

Node.js SDK

Use the official Nomiq Node.js SDK to integrate brand generation into JavaScript and TypeScript applications.

API Reference

Explore the full REST API reference, including all endpoints, request parameters, and response schemas.

​Requirements

​Projects

​Create a Project

​Retrieve a Project

​List Projects

​Delete a Project

​Brand Generation

​Handling Webhooks

​Error Handling

Node.js SDK

API Reference

Requirements

Projects

Create a Project

Retrieve a Project

List Projects

Delete a Project

Brand Generation

Handling Webhooks

Error Handling