API Referenz v1

Baut mit unserer API.

Die OnBeats REST-API ermöglicht es, Songs direkt aus deiner eigenen Anwendung zu generieren. Alle Anfragen laufen über deinen Account – Credits werden wie gewohnt abgezogen.

Base URL
https://onbeats.net/api/v1 · Alle Anfragen und Antworten sind JSON. · 10 Credits pro Song.

Voraussetzungen

Einen OnBeats-Account mit ausreichend Credits

Einen API-Key – erstelle ihn auf der API-Zugang Seite

Den Key im Authorization-Header jeder Anfrage mitschicken

Authentifizierung

Alle Endpoints erfordern einen gültigen API-Key. Sende ihn als Bearer-Token im HTTP-Header:

Header

Authorization: Bearer ob_your_api_key_here

Alternativ als Query-Parameter (nicht empfohlen für Produktion):

Query

GET /api/v1/credits?api_key=ob_your_api_key_here

Schicke deinen API-Key niemals an Client-seitigen Code (Browser-JavaScript). Nutze ihn nur serverseitig. Kompromittierte Keys kannst du jederzeit auf der API-Zugang Seite deaktivieren.

Fehler & HTTP-Status

Alle Antworten haben das Feld success: true/false. Fehlermeldungen stehen in error.

Fehler-Format

{
  "success": false,
  "error":   "Fehlerbeschreibung"
}

HTTP-Status-Codes

200

Erfolgreich

400

Ungültige Anfrage – Pflichtfelder fehlen oder sind falsch

401

Nicht autorisiert – API-Key fehlt oder ist ungültig/deaktiviert

402

Nicht genug Credits

404

Ressource nicht gefunden

405

HTTP-Methode nicht erlaubt

500

Serverfehler bei der Generierung

Credits abrufen

GET /api/v1/credits Kontostand & Generierungskapazität

Gibt den aktuellen Credit-Kontostand des authentifizierten Users zurück. Nützlich um vor einer Generierung zu prüfen ob genug Credits vorhanden sind.

Antwort

{
  "success":          true,
  "username":         "john",
  "credits":          150,
  "credits_per_song": 10,
  "can_generate":     true
}

Jetzt ausprobieren

API Key

Song generieren

POST /api/v1/generate Startet eine neue Song-Generierung

Startet die Generierung eines neuen Songs und gibt sofort eine song_id zurück. Die eigentliche Generierung läuft asynchron – benutze GET /api/v1/songs/{id} um den Status zu pollen. Pro Anfrage werden 10 Credits abgezogen.

Content-Type

Content-Type: application/json

Parameter – Simple Mode

Schicke nur prompt für einen einfachen Aufruf. Die KI bestimmt Stil und Struktur selbst.

Parameter	Typ	Pflicht	Beschreibung
prompt	string	Pflicht	Beschreibung des Songs (z.B. "Ein fröhlicher Sommerpop-Song")
is_public	boolean	Optional	Öffentlich sichtbar? Standard: `true`

Parameter – Advanced Mode

Volle Kontrolle über Titel, Style und Lyrics. Wird aktiviert wenn title und style gesetzt sind.

Parameter	Typ	Pflicht	Beschreibung
title	string	Pflicht	Titel des Songs (max. 255 Zeichen)
style	string	Pflicht	Stil-Beschreibung (z.B. "upbeat pop, electric guitar")
lyrics	string	Pflicht*	Liedtext (* außer bei `is_instrumental: true`)
is_instrumental	boolean	Optional	Instrumental ohne Gesang. Standard: `false`
is_public	boolean	Optional	Öffentlich sichtbar? Standard: `true`
genre	string	Optional	Genre-Slug (z.B. `pop`, `hip-hop`, `ambient`)

Beispiel – Simple Mode

JSON

{
  "prompt": "A happy summer pop song about the beach, female vocals"
}

Beispiel – Advanced Mode

JSON

{
  "title":          "Summer Vibes",
  "style":          "upbeat pop, electric guitar, sunny, female vocals",
  "lyrics":         "[Verse]\nSun on my face, sand between my toes\n[Chorus]\nSummer vibes...",
  "is_instrumental": false,
  "is_public":       true,
  "genre":          "pop"
}

Antwort

{
  "success":           true,
  "song_id":           123,
  "status":            "processing",
  "credits_used":      10,
  "credits_remaining": 140,
  "message":          "Song generation started. Poll /api/v1/songs/123 for status.",
  "song_url":         "https://onbeats.net/song/123"
}

Jetzt ausprobieren Verbraucht 10 Credits

API Key

Beschreibung (Simple Mode)

Song-Status abrufen

GET /api/v1/songs/{id} Status und Details eines Songs

Gibt den aktuellen Status und – wenn fertig – die Audio-URL eines Songs zurück. Nur Songs des authentifizierten Users werden zurückgegeben.

URL-Parameter

Parameter	Typ	Pflicht	Beschreibung
id	integer	Pflicht	Song-ID aus der Generate-Antwort

Status-Werte

pending

In der Warteschlange

processing

Wird gerade generiert

completed

Fertig – audio_url ist verfügbar

failed

Generierung fehlgeschlagen – Credits werden erstattet

Antwort (completed)

{
  "success": true,
  "song": {
    "id":         123,
    "title":      "Summer Vibes",
    "status":     "completed",
    "audio_url":  "https://onbeats.net/uploads/songs/song_123.mp3",
    "cover_url":  "https://onbeats.net/uploads/covers/cover_123.jpg",
    "duration":   180,
    "is_public":  true,
    "created_at": "2026-06-14 12:00:00",
    "song_url":   "https://onbeats.net/song/123"
  }
}

Jetzt ausprobieren

API Key

Song ID

Typischer Song-Flow

Da die Generierung asynchron abläuft, musst du den Status pollen:

Ablauf

1. POST /api/v1/generate   → Generierung starten, song_id erhalten
2. GET  /api/v1/songs/{id} → Status pollen (alle ~5 Sekunden)
3.  ↳ status = "pending"    → warten
   ↳ status = "processing" → warten
   ↳ status = "completed"  → audio_url verwenden ✅
   ↳ status = "failed"     → Fehler behandeln, Credits erstattet

Die Generierung dauert typischerweise 1–3 Minuten. Empfohlenes Poll-Intervall: alle 5 Sekunden. Timeout nach spätestens 10 Minuten einbauen.

Code-Beispiele

JavaScript (Node.js)

// Song generieren und auf Fertigstellung warten
async function generateSong(apiKey, prompt) {
  // 1. Generierung starten
  const res = await fetch('https://onbeats.net/api/v1/generate', {
    method:  'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type':  'application/json',
    },
    body: JSON.stringify({ prompt }),
  });
  const { song_id } = await res.json();

  // 2. Pollen bis fertig
  while (true) {
    await new Promise(r => setTimeout(r, 5000));
    const poll = await fetch(
      `https://onbeats.net/api/v1/songs/${song_id}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );
    const { song } = await poll.json();
    if (song.status === 'completed') return song.audio_url;
    if (song.status === 'failed')    throw new Error('Generation failed');
  }
}

PHP

// Song generieren und auf Fertigstellung warten
function generateSong($apiKey, $prompt): string {
  // 1. Generierung starten
  $ch = curl_init('https://onbeats.net/api/v1/generate');
  curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode(['prompt' => $prompt]),
    CURLOPT_HTTPHEADER     => [
      'Authorization: Bearer ' . $apiKey,
      'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
  ]);
  $data   = json_decode(curl_exec($ch), true);
  $songId = $data['song_id'];

  // 2. Pollen
  for ($i = 0; $i < 120; $i++) {
    sleep(5);
    $poll = json_decode(file_get_contents(
      'https://onbeats.net/api/v1/songs/' . $songId,
      context: stream_context_create(['http' => [
        'header' => 'Authorization: Bearer ' . $apiKey
      ]])
    ), true);
    if ($poll['song']['status'] === 'completed') return $poll['song']['audio_url'];
    if ($poll['song']['status'] === 'failed')    throw new \Exception('Generation failed');
  }
  throw new \Exception('Timeout');
}

Python

import requests, time

def generate_song(api_key: str, prompt: str) -> str:
    headers = {"Authorization": f"Bearer {api_key}"}

    # 1. Generierung starten
    r = requests.post(
        "https://onbeats.net/api/v1/generate",
        json={"prompt": prompt},
        headers=headers,
    )
    song_id = r.json()["song_id"]

    # 2. Pollen
    for _ in range(120):
        time.sleep(5)
        poll = requests.get(
            f"https://onbeats.net/api/v1/songs/{song_id}",
            headers=headers,
        ).json()["song"]
        if poll["status"] == "completed":
            return poll["audio_url"]
        if poll["status"] == "failed":
            raise Exception("Generation failed")
    raise TimeoutError()

cURL

# Credits prüfen
curl https://onbeats.net/api/v1/credits \
  -H "Authorization: Bearer ob_your_api_key"

# Song starten
curl -X POST https://onbeats.net/api/v1/generate \
  -H "Authorization: Bearer ob_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A calm lo-fi hip-hop beat for studying"}'

# Status pollen
curl https://onbeats.net/api/v1/songs/123 \
  -H "Authorization: Bearer ob_your_api_key"