Documentation

# Overview

Clients talk to this server as if it were an OpenAI-style API under /v1. Request and response bodies use familiar field names (model, prompt, data, …). Only models present in the local catalog are accepted — invented IDs are rejected.

# Base URL

Default listen address is http://127.0.0.1:3847 (override with HOST / PORT). API routes are under /v1.

http://127.0.0.1:3847/v1

# Authentication

Every generation endpoint requires an API key. Send it on each request:

Authorization: Bearer YOUR_API_KEY
# or
x-api-key: YOUR_API_KEY

Keys are verified on every call. An unknown or revoked key returns 401 invalid_api_key. Admin keys have no quotas; regular keys follow the limits below.

Public (no key): /health, /v1/models, /v1/status, /v1/config, docs UI. Everything that generates or costs credits is protected.

# Rate limits

Limits are per API key and apply to POST requests only. Polling a job, listing models or downloading audio is free.

Metered responses carry the remaining budget:

x-ratelimit-limit-minute: 3
x-ratelimit-remaining-minute: 2
x-ratelimit-limit-day: 500
x-ratelimit-remaining-day: 487

Exceeding a limit returns 429 with a retry_after value in seconds:

{
  "error": {
    "message": "Rate limit reached for music: 3 requests per minute. Retry in 42s.",
    "type": "rate_limit_error",
    "code": "rate_limited",
    "scope": "music",
    "limit": 3,
    "retry_after": 42
  }
}

Check your own consumption any time:

curl "http://127.0.0.1:3847/v1/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Quickstart

1. List models and pick a catalog id:

curl http://127.0.0.1:3847/v1/models

2. Generate an image:

curl -X POST http://127.0.0.1:3847/v1/images/generations \
  -H "Content-Type: application/json" \
  -d "{
    \"prompt\": \"a red fox in snow, cinematic\",
    \"model\": \"gpt-image-2\",
    \"aspect_ratio\": \"16:9\",
    \"quality\": \"medium\"
  }"

3. Poll the batch with the returned id:

curl "http://127.0.0.1:3847/v1/images/BATCH_ID"

# Endpoints

# Status

curl http://127.0.0.1:3847/v1/status

# Models

curl http://127.0.0.1:3847/v1/models

curl http://127.0.0.1:3847/v1/models/gpt-image-2

# Images

{
  "prompt": "a red fox in snow, cinematic",
  "model": "gpt-image-2",
  "aspect_ratio": "16:9",
  "resolution": "1K",
  "quality": "medium",
  "generations_count": 1,
  "wait": false
}

# Poll batch

curl "http://127.0.0.1:3847/v1/images/BATCH_ID"

# Music

Create songs with the v1 music model (lyrics or instrumental). Authenticate with the same API key as images. Poll until completed, or stream audio while status is streaming.

Recommended defaults

• Send a free-text prompt (style / mood). Prefer omitting tags.
• If you pass tags, include at least one tag (empty array is rejected).
• Strength: at most one of prompt_strength and style_scale may be > 1.0. Defaults: style_scale: 4.5, prompt_strength: 1.0.
• Instrumental: instrumental: true and no lyrics.
• With vocals: instrumental: false and required lyrics.

Statuses

# Music tags

curl "http://127.0.0.1:3847/v1/music/tags?q=synth&limit=20"

{
  "object": "list",
  "model": "v1",
  "data": ["synthpop", "…"],
  "count": 20,
  "total": 42,
  "offset": 0,
  "limit": 20,
  "q": "synth"
}

# Create track

curl -X POST http://127.0.0.1:3847/v1/music/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "dreamy synth-pop, warm pads",
    "lyrics": "Verse one...\nChorus...",
    "instrumental": false
  }'

curl -X POST http://127.0.0.1:3847/v1/music/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "dark trap, 140 BPM, heavy 808s", "instrumental": true }'

{
  "id": "mg_…",
  "object": "music.generation",
  "status": "queued",
  "model": "v1",
  "instrumental": false,
  "created": 1710000000,
  "variants": [
    { "id": "mg_…_a", "object": "music.variant", "status": "queued" },
    { "id": "mg_…_b", "object": "music.variant", "status": "queued" }
  ]
}

# Poll music

curl "http://127.0.0.1:3847/v1/music/generations/mg_…" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "mg_…_a",
  "object": "music.variant",
  "status": "completed",
  "title": "…",
  "duration": 182.4,
  "stream_url": null,
  "audio_url": "/v1/music/files/mg_…_a"
}

# Stream / file

curl -N "http://127.0.0.1:3847/v1/music/stream/mg_…_a" -o preview.ogg

curl "http://127.0.0.1:3847/v1/music/files/mg_…_a" -o track.ogg

# Logos

curl http://127.0.0.1:3847/v1/logos/openai?theme=dark
curl "http://127.0.0.1:3847/v1/logos/gpt-image-2?theme=light&redirect=0"

# Health

# Errors

Validation errors (client input):

{
  "error": {
    "message": "Validation failed",
    "type": "invalid_request_error",
    "code": "validation_error",
    "details": [ { "field": "model", "message": "…" } ]
  }
}

All other server-side failures use a generic shape (no internal details):

{
  "error": {
    "message": "Server Error. Please try again later.",
    "type": "server_error",
    "code": "server_error"
  }
}

# Limits & notes

• Model IDs must match the catalog — freestyle names are rejected.
• Parameter enums (aspect ratio, quality, resolution) are per-model.
• Catalog max_length is enforced by this API.
• CORS is open for local tools.

# Privacy