Generate Lyrics Package

POST/api/v1/lyrics/generateCopy URL

Authentication · x-api-key

Create a GPT lyrics-generation task, persist it through the unified task pipeline, and wait briefly for the completed result.

All endpointsRequestResponsesCode

Request

Idempotency-Keyheader · Optional

string

Unique key for one logical write. Retrying the same body with the same key replays the original result; reusing it with a different body returns 409.

Maximum characters: 255.

Unknown fields are not accepted.

• Request · promptRequired

  string

  Core song brief, story, scene, or hook idea.

  Maximum characters: 2000.

• Request · configOptional

  object

  Standard task configuration: priority, tags, metadata, and webhookUrl.

  4 fields

  • Request · config.metadataOptional

    object

    Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.

  • Request · config.priorityOptional

    number

    Task priority 1-10 (higher = sooner). Default 5.

    Minimum: 1. Maximum: 10. Default: 5.

  • Request · config.tagsOptional

    array<string>

    Free-form labels for filtering. Up to 20, 100 chars each.

    Maximum items: 20.

    1 field

    • Request · config.tags[]Each item

      string

      Maximum characters: 100.

  • Request · config.webhookUrlOptional

    string

    URL to receive task.* lifecycle events via the central webhook service.

    Format: uri.

• Request · durationSecOptional

  number

  Target duration in seconds.

  Minimum: 30. Maximum: 480.

• Request · explicitOptional

  boolean

  Whether explicit language is acceptable.

• Request · extraGuidanceOptional

  string

  Additional creative guidance or constraints.

  Maximum characters: 2000.

• Request · genreOptional

  string

  Requested musical genre direction.

  Maximum characters: 200.

• Request · languageOptional

  string

  Primary lyric language. Use 'auto' to let the model decide.

  Maximum characters: 80.

• Request · languagesOptional

  array<string>

  Additional languages to include or consider.

  1 field

  • Request · languages[]Each item

    string

    Additional languages to consider for multilingual lyrics.

    Maximum characters: 80.

• Request · modeOptional

  "gpt"

  Lyrics generation mode. GPT is the supported mode.

• Request · moodOptional

  string

  Requested musical or visual mood.

  Maximum characters: 200.

• Request · multilingualModeOptional

  "auto" | "sectioned" | "blended" | "call_and_response"

  How multiple languages should be mixed.

• Request · negativeConstraintsOptional

  array<string>

  Topics, styles, or tropes the output should avoid.

  1 field

  • Request · negativeConstraints[]Each item

    string

    Styles, topics, or tropes to avoid.

    Maximum characters: 80.

• Request · perspectiveOptional

  "first_person" | "second_person" | "third_person" | "mixed"

  Requested lyric narrative perspective.

• Request · structureOptional

  array<string>

  Requested lyric section order.

  1 field

  • Request · structure[]Each item

    string

    Requested section order, e.g. Verse 1, Chorus, Bridge.

    Maximum characters: 50.

• Request · themeKeywordsOptional

  array<string>

  Short theme keywords to anchor the lyrics.

  1 field

  • Request · themeKeywords[]Each item

    string

    Maximum characters: 60.

• Request · vocalStyleOptional

  string

  Requested vocal performance direction.

  Maximum characters: 200.

Responses

200 OK

application/json

• Response 200 · creditsChargedRequired

  number

• Response 200 · hookRequired

  string

• Response 200 · languagePlanRequired

  object
  4 fields

  • Response 200 · languagePlan.mixStrategyRequired

    string

  • Response 200 · languagePlan.primaryLanguageRequired

    string

  • Response 200 · languagePlan.secondaryLanguagesRequired

    array<string>
    1 field

    • Response 200 · languagePlan.secondaryLanguages[]Each item

      string

  • Response 200 · languagePlan.transliterationRequired

    string | null

    May be null. Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · languagePlan.transliteration · anyOf 1Alternative

      string

    • Response 200 · languagePlan.transliteration · anyOf 2Alternative

      null

• Response 200 · lyricsRequired

  string

• Response 200 · modelRequired

  string

• Response 200 · modelPathRequired

  string

• Response 200 · notesRequired

  array<string>
  1 field

  • Response 200 · notes[]Each item

    string

• Response 200 · producerRequired

  object
  3 fields

  • Response 200 · producer.lyricsRequired

    string

  • Response 200 · producer.soundPromptRequired

    string

  • Response 200 · producer.titleRequired

    string

• Response 200 · sectionOrderRequired

  array<string>
  1 field

  • Response 200 · sectionOrder[]Each item

    string

• Response 200 · statusRequired

  "COMPLETED"

• Response 200 · sunoRequired

  object
  4 fields

  • Response 200 · suno.negativeTagsRequired

    string | null

    May be null. Must match at least one alternative.

    2 fields / alternatives

    • Response 200 · suno.negativeTags · anyOf 1Alternative

      string

    • Response 200 · suno.negativeTags · anyOf 2Alternative

      null

  • Response 200 · suno.promptRequired

    string

  • Response 200 · suno.tagsRequired

    string

  • Response 200 · suno.titleRequired

    string

• Response 200 · taskIdRequired

  string

• Response 200 · titleRequired

  string

• Response 200 · usageOptional

  object
  3 fields

  • Response 200 · usage.completionTokensOptional

    number

  • Response 200 · usage.promptTokensOptional

    number

  • Response 200 · usage.totalTokensOptional

    number

202 Accepted

application/json

• Response 202 · creditsRequiredRequired

  number

• Response 202 · messageRequired

  string

• Response 202 · modelPathRequired

  string

• Response 202 · pollUrlRequired

  string

• Response 202 · statusRequired

  "PENDING" | "PROCESSING"

• Response 202 · taskIdRequired

  string

400 Bad Request

application/json

• Response 400 · errorRequired

  object
  3 fields

  • Response 400 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 400 · error.messageRequired

    string

    Human readable error message

  • Response 400 · error.detailsOptional

    object

    Additional error details (optional)

• Response 400 · successRequired

  false

  Always false for error responses

401 Unauthorized

application/json

• Response 401 · errorRequired

  object
  3 fields

  • Response 401 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 401 · error.messageRequired

    string

    Human readable error message

  • Response 401 · error.detailsOptional

    object

    Additional error details (optional)

• Response 401 · successRequired

  false

  Always false for error responses

402 Payment Required

application/json

• Response 402 · errorRequired

  object
  3 fields

  • Response 402 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 402 · error.messageRequired

    string

    Human readable error message

  • Response 402 · error.detailsOptional

    object

    Additional error details (optional)

• Response 402 · successRequired

  false

  Always false for error responses

403 Forbidden

Forbidden: the API key lacks the required scope or its IP policy rejects this request. Forbidden: API-key scope/IP restrictions or billing hold. A positive balance does not bypass payment review. Check GET /api/v1/account/credits billingStatus before further paid requests.

application/json

• Response 403 · errorRequired

  object
  3 fields

  • Response 403 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 403 · error.messageRequired

    string

    Human readable error message

  • Response 403 · error.detailsOptional

    object

    Additional error details (optional)

• Response 403 · successRequired

  false

  Always false for error responses

409 Conflict

application/json

• Response 409 · errorRequired

  object
  3 fields

  • Response 409 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 409 · error.messageRequired

    string

    Human readable error message

  • Response 409 · error.detailsOptional

    object

    Additional error details (optional)

• Response 409 · successRequired

  false

  Always false for error responses

429 Too Many Requests

Request allowance or task admission capacity exceeded. Follow Retry-After when present; otherwise wait for active tasks and use bounded backoff. Limits do not guarantee throughput. For SSE, this is the HTTP connection response, not an event.

application/json

• Response 429 · errorRequired

  object
  3 fields

  • Response 429 · error.codeRequired

    string

    RATE_LIMITED for request and task admission rejections.

  • Response 429 · error.messageRequired

    string

  • Response 429 · error.detailsOptional

    object

    Optional and scope-dependent. Request limits supply scope/policy/type/limit/current/retryAfterSec. Task admission supplies inFlight/limit/tier, plus scope=apiKey for a key cap. IP rejection can omit details. In-flight rejection does not promise Retry-After.

    8 fields

    • Response 429 · error.details.currentOptional

      integer

      Minimum: 0.

    • Response 429 · error.details.inFlightOptional

      integer

      Minimum: 0.

    • Response 429 · error.details.limitOptional

      integer

      Minimum: 0.

    • Response 429 · error.details.policyOptional

      "operation" | "query"

    • Response 429 · error.details.retryAfterSecOptional

      integer

      Minimum: 1.

    • Response 429 · error.details.scopeOptional

      "user" | "api-key" | "ip" | "apiKey"

    • Response 429 · error.details.tierOptional

      "FREE" | "PREMIUM" | "ENTERPRISE"

    • Response 429 · error.details.typeOptional

      "rps" | "daily" | "monthly"

• Response 429 · successRequired

  false

  Default: false.

500 Internal Server Error

application/json

• Response 500 · errorRequired

  object
  3 fields

  • Response 500 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 500 · error.messageRequired

    string

    Human readable error message

  • Response 500 · error.detailsOptional

    object

    Additional error details (optional)

• Response 500 · successRequired

  false

  Always false for error responses

502 Bad Gateway

application/json

• Response 502 · errorRequired

  object
  3 fields

  • Response 502 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 502 · error.messageRequired

    string

    Human readable error message

  • Response 502 · error.detailsOptional

    object

    Additional error details (optional)

• Response 502 · successRequired

  false

  Always false for error responses

503 Service Unavailable

application/json

• Response 503 · errorRequired

  object
  3 fields

  • Response 503 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 503 · error.messageRequired

    string

    Human readable error message

  • Response 503 · error.detailsOptional

    object

    Additional error details (optional)

• Response 503 · successRequired

  false

  Always false for error responses

Request example

Wrap lines

cURL

curl --globoff --request POST \
  --url 'https://api.omnapi.com/api/v1/lyrics/generate' \
  --header "x-api-key: $OMNAPI_KEY" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header 'Content-Type: application/json' \
  --data @request.json

Node.js

import { readFile } from "node:fs/promises";
const response = await fetch("https://api.omnapi.com/api/v1/lyrics/generate", {
  method: "POST",
  headers: {
    "x-api-key": process.env.OMNAPI_KEY,
    "Idempotency-Key": process.env.IDEMPOTENCY_KEY,
    "Content-Type": "application/json",
  },
  body: await readFile("request.json", "utf8"),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.text());

Python

import os, json
import requests

response = requests.request(
    "POST", "https://api.omnapi.com/api/v1/lyrics/generate",
    headers={
        "x-api-key": os.environ["OMNAPI_KEY"],
        "Idempotency-Key": os.environ["IDEMPOTENCY_KEY"],
    },
    json=json.load(open("request.json")),
    timeout=60,
)
response.raise_for_status()
print(response.text)

Set URL and header variables. Save your JSON body as request.json. Reuse the same IDEMPOTENCY_KEY and body on retries.

Interactive API Explorer → · OpenAPI JSON