List reusable creative versions

GET/api/v2/mv/creative-projectsCopy URL

Authentication · x-api-key

Omn V1 independent product API. Independent Omn request, planning and delivery semantics.

Scope: task:read

Billing and effects: Free resource read; no generation purchase.

Recovery: Read the current resource before retrying a mutation; do not assume this operation supports Idempotency-Key.

Follow this operation’s workflow → · All permission rules

API v2 is the recommended interface for new Omn integrations. It uses the Omn V1 generation engine. Authenticate with an API key and check capabilities/preflight before purchasing. API availability

All endpointsRequestResponsesCode

Request

No request parameters.

Responses

Read the HTTP status and body together. A receipt confirms acceptance; poll the returned Task or product view for terminal execution and media delivery. Example IDs and credit amounts are illustrative, not a price quote.

HTTP 401 · Request rejected; correct the key before retrying

Complete JSON example (optional fields may be omitted).

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

200 OK

application/json

Required, optional and null

Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

Only the listed fields are accepted in this object.

• Response 200 · projectsRequired

  array<object>

  Up to 100 unarchived creative projects owned by the caller, newest first, each associated with a specific song version.

  1 field

  • Response 200 · projects[]Each item

    object

    Only the listed fields are accepted in this object.

    6 fields

    • Response 200 · projects[].durationSecRequired

      number

      Duration in seconds for the containing media, selection or operation. Use validated duration when authorizing a purchase.

    • Response 200 · projects[].idRequired

      string

      Identifier of this resource. Keep identifiers for Tasks, product resources and child assets separately; use the ID required by the destination endpoint.

    • Response 200 · projects[].revisionsRequired

      array<object>

      Up to 50 PUBLISHED creative revisions for this project, newest first; unpublished revisions are excluded.

      1 field

      • Response 200 · projects[].revisions[]Each item

        object

        Only the listed fields are accepted in this object.

        5 fields

        • Response 200 · projects[].revisions[].activeRequired

          boolean

          Whether this revision is the project's currently active revision.

        • Response 200 · projects[].revisions[].conceptRequired

          string

          Concept text extracted from the stored creative bible, or an empty string when none is stored.

        • Response 200 · projects[].revisions[].createdAtRequired

          string

          Creation timestamp in the format shown below; JSON date-time values include their timezone.

        • Response 200 · projects[].revisions[].creativeRequired

          object | null

          Creative intent, independent of output resolution.

          Use a complete option below; the value must satisfy at least one option.

          2 options

          • Response 200 · Option 1 — mode = "auto" | "story" (+6 more values)Option

            object

            Creative intent, independent of output resolution.

            Only the listed fields are accepted in this object.

            6 fields

            • Response 200 · projects[].revisions[].creative.modeRequired

              "auto" | "story" | "mood" | "perform" | "sing" | "dance" | "sing_dance" | "sing_play"

              auto, story, mood, perform, sing, dance, sing_dance or sing_play. All use the same request envelope.

              Default: "auto".

            • Response 200 · projects[].revisions[].creative.briefOptional

              string

              Describe the desired story, subjects, action and mood. Required for a brief-led story.

              Maximum characters: 3000.

            • Response 200 · projects[].revisions[].creative.charactersOptional

              object

              Whether characters may appear and the desired count.

              Only the listed fields are accepted in this object.

              2 fields

              • Response 200 · projects[].revisions[].creative.characters.policyRequired

                "auto" | "required" | "forbidden"

                auto lets the director decide; required mandates characters; forbidden excludes them and conflicts with performance modes or character references.

                Default: "auto".

              • Response 200 · projects[].revisions[].creative.characters.countOptional

                string | integer

                Desired number of main characters (1 or 2); cannot be combined with forbidden.

                Minimum: 1. Maximum: 2. Use a complete option below; the value must satisfy at least one option.

                2 options

                • Response 200 · Option 1 — stringOption

                  string

                  Numeric string accepted by coercion; the converted value must satisfy the numeric constraints (minimum 1, maximum 2). Prefer a JSON number.

                  Format: integer.

                • Response 200 · Option 2 — integerOption

                  integer

                  Desired number of main characters (1 or 2); cannot be combined with forbidden.

                  Minimum: 1. Maximum: 2.

            • Response 200 · projects[].revisions[].creative.continuityOptional

              object

              Optional reuse of a creative project/revision. Omit for an independent request; selected revisions must belong to the same audio and project.

              Only the listed fields are accepted in this object.

              4 fields

              • Response 200 · projects[].revisions[].creative.continuity.boundaryPolicyOptional

                "standalone" | "excerpt"

                How the selected range is presented: excerpt preserves its relationship to the song; standalone treats it as an independent piece. Default excerpt.

                Default: "standalone".

              • Response 200 · projects[].revisions[].creative.continuity.projectIdOptional

                string

                Creative project identifier returned by the project list. Reuse only a project owned by your account and matching this audio.

                Minimum characters: 1. Maximum characters: 128.

              • Response 200 · projects[].revisions[].creative.continuity.revisionIdOptional

                string

                Creative revision identifier returned by the project list. Reusing it preserves the chosen direction; an incompatible audio source or mode returns a conflict.

                Minimum characters: 1. Maximum characters: 128.

              • Response 200 · projects[].revisions[].creative.continuity.sourceScopeOptional

                "full_song" | "fragment" | "unknown"

                Declared source extent: full_song, fragment or unknown. Default unknown; this declaration does not replace media validation.

                Default: "full_song".

            • Response 200 · projects[].revisions[].creative.optionsOptional

              object

              Mode-specific choices; irrelevant options are rejected.

              Only the listed fields are accepted in this object.

              3 fields

              • Response 200 · projects[].revisions[].creative.options.combinationOptional

                "alternating" | "simultaneous"

                Required for sing_dance or sing_play. alternating uses separate shots. simultaneous requests same-shot actions and currently returns 422 before debit.

                Default: "alternating".

              • Response 200 · projects[].revisions[].creative.options.instrumentOptional

                string

                Instrument to feature in perform or sing_play.

                Minimum characters: 1. Maximum characters: 100.

              • Response 200 · projects[].revisions[].creative.options.storySourceOptional

                "lyrics" | "brief"

                Required for story: lyrics uses song evidence; brief uses creative.brief.

                Default: "lyrics".

            • Response 200 · projects[].revisions[].creative.styleOptional

              string

              Visual treatment passed to director planning and shot generation.

              Maximum characters: 1000.

          • Response 200 · Option 2 — nullOption

            null

        • Response 200 · projects[].revisions[].idRequired

          string

          Identifier of this resource. Keep identifiers for Tasks, product resources and child assets separately; use the ID required by the destination endpoint.

    • Response 200 · projects[].songVersionIdRequired

      string

      Canonical song/audio version to which this creative project belongs; reuse requires a compatible audio source.

    • Response 200 · projects[].sourceScopeRequired

      string

      Declared source extent: full_song, fragment or unknown. Default unknown; this declaration does not replace media validation.

    • Response 200 · projects[].versionRequired

      string | integer

      Current resource revision. Use it as expectedVersion when updating that resource to detect concurrent edits.

      Use a complete option below; the value must satisfy at least one option.

      2 options

      • Response 200 · Option 1 — stringOption

        string

        Numeric string accepted by coercion; the converted value must satisfy the numeric constraints. Prefer a JSON number.

        Format: integer.

      • Response 200 · Option 2 — integerOption

        integer

400 Bad Request

application/json

Required, optional and null

Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

• Response 400 · errorRequired

  object

  Structured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.

  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

    Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

    1 field

    • Response 400 · error.details[key]Each value

      any JSON value

      Key pattern: ^(.*)$.

• Response 400 · successRequired

  false

  Always false for error responses

401 Unauthorized

application/json

Required, optional and null

Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

• Response 401 · errorRequired

  object

  Structured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.

  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

    Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

    1 field

    • Response 401 · error.details[key]Each value

      any JSON value

      Key pattern: ^(.*)$.

• Response 401 · successRequired

  false

  Always false for error responses

402 Payment Required

application/json

Required, optional and null

Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

• Response 402 · errorRequired

  object

  Structured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.

  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

    Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

    1 field

    • Response 402 · error.details[key]Each value

      any JSON value

      Key pattern: ^(.*)$.

• Response 402 · successRequired

  false

  Always false for error responses

403 Forbidden

application/json

Required, optional and null

Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

• Response 403 · errorRequired

  object

  Structured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.

  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

    Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

    1 field

    • Response 403 · error.details[key]Each value

      any JSON value

      Key pattern: ^(.*)$.

• Response 403 · successRequired

  false

  Always false for error responses

404 Not Found

application/json

Required, optional and null

Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

• Response 404 · errorRequired

  object

  Structured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.

  3 fields

  • Response 404 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 404 · error.messageRequired

    string

    Human readable error message

  • Response 404 · error.detailsOptional

    object

    Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

    1 field

    • Response 404 · error.details[key]Each value

      any JSON value

      Key pattern: ^(.*)$.

• Response 404 · successRequired

  false

  Always false for error responses

409 Conflict

application/json

Required, optional and null

Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

• Response 409 · errorRequired

  object

  Structured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.

  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

    Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

    1 field

    • Response 409 · error.details[key]Each value

      any JSON value

      Key pattern: ^(.*)$.

• Response 409 · successRequired

  false

  Always false for error responses

413 Payload Too Large

application/json

Required, optional and null

Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

• Response 413 · errorRequired

  object

  Structured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.

  3 fields

  • Response 413 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 413 · error.messageRequired

    string

    Human readable error message

  • Response 413 · error.detailsOptional

    object

    Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

    1 field

    • Response 413 · error.details[key]Each value

      any JSON value

      Key pattern: ^(.*)$.

• Response 413 · successRequired

  false

  Always false for error responses

422 Unprocessable Entity

application/json

Required, optional and null

Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

• Response 422 · errorRequired

  object

  Structured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.

  3 fields

  • Response 422 · error.codeRequired

    string

    Application-specific error code (see error catalog)

  • Response 422 · error.messageRequired

    string

    Human readable error message

  • Response 422 · error.detailsOptional

    object

    Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

    1 field

    • Response 422 · error.details[key]Each value

      any JSON value

      Key pattern: ^(.*)$.

• Response 422 · 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

Required, optional and null

Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

• Response 429 · errorRequired

  object

  Structured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.

  3 fields

  • Response 429 · error.codeRequired

    string

    RATE_LIMITED for request and task admission rejections.

  • Response 429 · error.messageRequired

    string

    Human-readable explanation. Wording may change; use the machine-readable code for programmatic decisions.

  • Response 429 · error.detailsOptional

    object

    Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

    9 fields

    • Response 429 · error.details.currentOptional

      integer

      Current count for the rate-limit window identified by policy and scope.

      Minimum: 0.

    • Response 429 · error.details.inFlightOptional

      integer

      Current accepted tasks counted against the relevant account or API-key admission limit.

      Minimum: 0.

    • Response 429 · error.details.limitOptional

      integer

      Maximum count allowed by this response context. A limit is not a throughput guarantee.

      Minimum: 0.

    • Response 429 · error.details.policyOptional

      "operation" | "query"

      Allowance bucket: query for resource reads, operation for task-producing or operation requests. See the rate-limit response headers.

    • Response 429 · error.details.retryAfterSecOptional

      integer

      Suggested delay in seconds before another request. Honor the Retry-After header when present; use bounded backoff.

      Minimum: 1.

    • Response 429 · error.details.scopeOptional

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

      Entity whose allowance was exceeded, such as the user, API key or IP address.

    • Response 429 · error.details.tierOptional

      "FREE" | "PREMIUM" | "ENTERPRISE"

      Account allowance tier used for this admission or rate-limit decision.

    • Response 429 · error.details.typeOptional

      "rps" | "daily" | "monthly"

      Admission limit that rejected the request: rps (continuously refilled requests-per-second bucket), daily or monthly UTC request budget. Interpret with policy, scope and retryAfterSec.

    • Response 429 · error.details[key]Each value

      any JSON value

      Key pattern: ^(.*)$.

• Response 429 · successRequired

  false

  Whether this response reports a successful action; false accompanies the structured error object.

  Default: false.

500 Internal Server Error

application/json

Required, optional and null

Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

• Response 500 · errorRequired

  object

  Structured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.

  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

    Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

    1 field

    • Response 500 · error.details[key]Each value

      any JSON value

      Key pattern: ^(.*)$.

• Response 500 · successRequired

  false

  Always false for error responses

502 Bad Gateway

application/json

Required, optional and null

Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

• Response 502 · errorRequired

  object

  Structured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.

  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

    Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

    1 field

    • Response 502 · error.details[key]Each value

      any JSON value

      Key pattern: ^(.*)$.

• Response 502 · successRequired

  false

  Always false for error responses

503 Service Unavailable

application/json

Required, optional and null

Required fields apply within their object and selected option. An optional object may be absent; when present, its required fields must be included. Required and nullable are independent: null is allowed only where listed.

• Response 503 · errorRequired

  object

  Structured failure information. Branch on code, show message, and interpret details only for that code. The request ID is returned in the X-Request-Id header.

  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

    Optional error-specific context. Read code first; details keys depend on that code. Unknown keys must not break error handling. See /resources/errors/.

    1 field

    • Response 503 · error.details[key]Each value

      any JSON value

      Key pattern: ^(.*)$.

• Response 503 · successRequired

  false

  Always false for error responses

Request example

Wrap lines

cURL

curl --globoff --request GET \
  --url 'https://api.omnapi.com/api/v2/mv/creative-projects' \
  --header "x-api-key: $OMNAPI_KEY"

Node.js

const response = await fetch("https://api.omnapi.com/api/v2/mv/creative-projects", {
  method: "GET",
  headers: {
    "x-api-key": process.env.OMNAPI_KEY,
  },
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.text());

Python

import os
import requests

response = requests.request(
    "GET", "https://api.omnapi.com/api/v2/mv/creative-projects",
    headers={
        "x-api-key": os.environ["OMNAPI_KEY"],
    },
    timeout=60,
)
response.raise_for_status()
print(response.text)

Replace URL placeholders such as {taskId} with IDs from actual responses, and set the header environment variables shown above.

Workflow and next steps → · Recover an uncertain request

Interactive API Explorer → · OpenAPI JSON