Developer Docs

Identity Market API

Generate images using governed AI identities through a hosted API with authenticated access and usage tracking.

Developer Documentation

Generation API Reference

Programmatic access to AI identity generation. Authenticate with API keys, submit generation requests, and retrieve generated images through Identity Market's managed inference runtime.

Overview

The Identity Market API lets you generate images with creator systems via authenticated HTTP requests. The main generate endpoint validates access, runs the managed runtime, and returns outputs in the same response.

Base URL

https://identity-market.com/api/v1

Identity Market uses a subscription-based API model. Access is authenticated via API key and tracked against the active access record behind that key. Creator systems remain on platform infrastructure and are never distributed as raw files.

Getting Started

Three steps to your first generation. Once you have a paid Starter or Pro plan, the basic flow is: create a key, choose a system, then call /generate.

1

Create an API key

Open your Dashboard, navigate to API Access, and click "Generate API Key". Copy the key immediately - it is shown only once.

2

Choose a system and generate

Use the system ID shown on the marketplace detail page, then send a POST request with that ID and your prompt. If your plan includes the founding creator catalog, the same key can call any included launch system.

bash
curl -X POST https://identity-market.com/api/v1/generate \
  -H "Authorization: Bearer aim_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"identityId":"YOUR_SYSTEM_ID","prompt":"professional campaign portrait, tailored suit, premium studio lighting"}'
3

Test the same flow in the playground

The hosted playground in Account uses the same backend pipeline if you want to test generation and confirm a system ID before integrating.

Authentication

All programmatic generate requests require a Bearer token in the Authorization header. API keys are prefixed with aim_live_ and are created from an active access record in your dashboard.

Getting an API Key

  1. Purchase a Starter or Pro subscription, or a specialist system with API access
  2. Open your Dashboard
  3. Click "Generate API Key" under the API Access section
  4. Copy the key immediately - it is shown only once

Keys are attached to the access record they were created from. A key tied to a bundled core plan can call any included founding catalog system. Specialist systems still require access to that specific system.

Example Request
curl -X POST https://identity-market.com/api/v1/generate \
  -H "Authorization: Bearer aim_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"identityId":"YOUR_IDENTITY_ID","prompt":"premium skincare campaign, soft editorial lighting","referenceImages":[{"url":"https://example.com/product-shot.png"}],"referenceMode":"exact_product","preserveBranding":true}'

Submit Generation Request

POST/generate

Submit a generation request for an identity your key is authorized to use. The API validates access, checks usage, runs the managed workflow, and returns outputs in the same response.

Product-photo ready identities can also accept reference-image inputs. The identity still owns the workflow behavior; clients only pass the campaign prompt plus optional product references.

Request Body

FieldTypeRequiredDescription
identityIdstringYesDatabase identity ID from the marketplace detail page
promptstringYesGeneration prompt (max 1000 characters)
negativePromptstringNoNegative prompt (max 500 characters)
seedintegerNoRandom seed. If omitted, the server chooses one.
numInferenceStepsintegerNoInference steps, 20-50 (default: 30)
guidanceScalefloatNoGuidance scale, 1-20 (default: 7.5)
numOutputsintegerNoRequested outputs, capped by tier (1 for Standard, 4 for Pro)
widthintegerNoWidth in pixels. Multiples of 64 only, minimum 512, capped by tier (1024px Standard / 2048px Pro)
heightintegerNoHeight in pixels. Multiples of 64 only, minimum 512, capped by tier (1024px Standard / 2048px Pro)
referenceImagesarrayNoOptional reference image inputs for product-photo capable identities. Each item can include a temporary upload reference or HTTPS image URL.
referenceModestringNoReference behavior hint: exact_product or reference.
preserveBrandingbooleanNoAsk the hosted workflow to keep packaging, logo, and label details accurate where supported.

Response - 200 OK

JSON
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "outputs": ["https://identity-market.com/api/files/generated/example-output.png?signature=..."],
  "identity": {
    "id": "YOUR_IDENTITY_ID",
    "name": "James-X10"
  },
  "referenceImagesUsed": 1,
  "usage": {
    "creditsUsed": 43,
    "creditsLimit": 500,
    "creditsRemaining": 457,
    "creditsCharged": 4,
    "periodResetDate": "2026-03-01T00:00:00.000Z"
  },
  "processingTimeMs": 8421,
  "seed": 38127419
}

Check Generation Status

GET/generate/{requestId}

Re-fetch a stored generation request by request ID. This is useful for dashboard history, retry workflows, or checking a request later without regenerating.

Response - 200 OK

JSON
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "COMPLETED",
  "identity": { "name": "James-X10", "slug": "james-x10" },
  "prompt": "professional headshot, business attire",
  "seed": 38127419,
  "steps": 30,
  "cfgScale": 7.5,
  "width": 1024,
  "height": 1024,
  "outputUrl": "https://identity-market.com/api/files/generated/example-output.png?signature=...",
  "errorMessage": null,
  "createdAt": "2026-02-26T10:00:00.000Z",
  "startedAt": "2026-02-26T10:00:01.000Z",
  "completedAt": "2026-02-26T10:00:12.000Z"
}

Possible statuses: QUEUED PROCESSING COMPLETED FAILED TIMEOUT

Query Usage Statistics

GET/usage?licenseId={licenseId}

Returns current usage, limits, billing period, and recent request history for a subscription access record. This endpoint is session-authenticated for the account dashboard - it does not accept API keys.

Response - 200 OK

JSON
{
  "licenseId": "LICENSE_ID",
  "stats": {
    "current": 43,
    "limit": 500,
    "percentage": 4,
    "billingPeriodStart": "2026-02-01T00:00:00.000Z",
    "billingPeriodEnd": "2026-03-03T00:00:00.000Z",
    "daysRemaining": 5,
    "tier": "API_STANDARD"
  },
  "history": [],
  "aggregates": { "byType": {}, "byIdentity": {} }
}

API Key Management

These endpoints back the dashboard and require a logged-in account session. They are useful for internal tooling, but most customers create and revoke keys directly in the dashboard UI.

POST/keys

Generate a new API key for a subscription access record. Body: {"licenseId":"...","name":"My Key"}. The raw key is returned only once.

GET/keys

List all API keys for the authenticated user. Returns key metadata, never the full raw key.

DELETE/keys/{keyId}

Revoke an API key immediately. Revoked keys cannot be used for any further requests.

Webhooks

Generation webhooks are not part of the public subscriber API today. For now, use the synchronous response from POST /generate, re-check request records via GET /generate/{requestId}, or use Dashboard history. Stripe webhooks exist internally for billing and subscription lifecycle management, but they are not a customer integration surface.

Code Examples

Python

python
import requests

API_KEY = "aim_live_your_api_key_here"
BASE = "https://identity-market.com/api/v1"

response = requests.post(
    f"{BASE}/generate",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "identityId": "YOUR_IDENTITY_ID",
        "prompt": "professional headshot, business attire",
        "width": 1024,
        "height": 1024,
        "numOutputs": 1,
        "numInferenceSteps": 30,
        "guidanceScale": 7.5,
    },
)
response.raise_for_status()

data = response.json()
print(data["outputs"])
print(data["usage"])

JavaScript / Node.js

javascript
const API_KEY = "aim_live_your_api_key_here";
const BASE = "https://identity-market.com/api/v1";

async function generate() {
  const response = await fetch(`${BASE}/generate`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      identityId: "YOUR_IDENTITY_ID",
      prompt: "professional headshot",
      width: 1024,
      height: 1024,
      numOutputs: 1,
      numInferenceSteps: 30,
      guidanceScale: 7.5,
    }),
  });

  if (!response.ok) {
    throw new Error(JSON.stringify(await response.json()));
  }

  const data = await response.json();
  console.log("requestId:", data.requestId);
  console.log("outputs:", data.outputs);
  console.log("usage:", data.usage);
}

generate();

cURL

bash
curl -s -X POST https://identity-market.com/api/v1/generate \
  -H "Authorization: Bearer aim_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "identityId":"YOUR_IDENTITY_ID",
    "prompt":"professional headshot",
    "width":1024,
    "height":1024,
    "numOutputs":1,
    "numInferenceSteps":30,
    "guidanceScale":7.5
  }'

Rate Limits

Generation access is metered by plan. In addition to monthly call limits, routes also have short-window protection to prevent abuse. When exceeded, the API returns 429 Too Many Requests.

TierCredits / MonthMax Outputs / RequestMax ResolutionPrice
Starter50011024px$19/mo
Standard1,50042048px$39/mo
Pro4,00042048px$75/mo
EnterpriseCustom42048pxCustom
  • Generate submits: 10/minute per API key
  • Generation status checks: 60/minute
  • Usage dashboard queries: 30/minute with account session auth

Error Codes

Error responses use the shape {"error":"...","code":"..."}.

401
INVALID_API_KEY

API key is missing, invalid, expired, or revoked.

400
INVALID_BODY

Request body could not be parsed as JSON.

400
MISSING_IDENTITY

identityId is required.

404
IDENTITY_NOT_FOUND

The requested identity ID does not exist.

401
IDENTITY_MISMATCH

The key is valid but not authorized for the requested identity.

400
INVALID_PARAMETERS

Prompt or generation parameters failed validation.

400
TIER_LIMIT

Requested resolution or outputs exceed the active tier.

429
CREDIT_LIMIT_EXCEEDED

The monthly credit limit for this access record has been reached.

503
IDENTITY_UNAVAILABLE

No active inference model is available for the requested identity.

503
SERVICE_UNAVAILABLE

The inference backend is temporarily degraded or unavailable.

504
TIMEOUT

Generation timed out after starting.

500
GENERATION_FAILED

Generation failed after the request was accepted.

Best Practices

  • 1.Check usage before bulk requests. Use the dashboard usage view or the session-authenticated GET /usage endpoint to verify remaining quota.
  • 2.Implement exponential back-off for 429 responses. Start at 1 s, double each retry, and cap at 60 s.
  • 3.Store request IDs. The generate endpoint is synchronous, but saving requestId makes auditing and later status lookups easier.
  • 4.Keep prompts within the documented limits. Large prompt payloads and invalid sizes are rejected before inference starts.
  • 5.Use fixed seeds for reproducible results across identical prompts and parameters.
  • 6.Rotate API keys regularly and revoke any compromised key immediately from the dashboard.
  • 7.Never commit API keys to source control. Store them in environment variables or a secrets manager.

Need help integrating?

support@identity-market.com