{ "components": { "headers": { "X-RateLimit-Limit": { "description": "Reported allowance; 0 means no hard cap. May be omitted when protection is disabled or before the check runs.", "schema": { "minimum": 0, "type": "integer" } }, "X-RateLimit-Policy": { "description": "Present for customer/key checks. Only GET /api/v1/tasks/{id} uses query; opening an SSE stream uses operation.", "schema": { "enum": [ "operation", "query" ], "type": "string" } }, "X-RateLimit-Remaining": { "description": "Remaining capacity in the reported allowance.", "schema": { "minimum": 0, "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp in seconds for calendar reset or rate-capacity recovery.", "schema": { "minimum": 0, "type": "integer" } }, "X-RateLimit-Scope": { "description": "Allowance reported by the last applicable check; an earlier IP rejection reports ip.", "schema": { "enum": [ "user", "api-key", "ip" ], "type": "string" } }, "X-RateLimit-Type": { "description": "Kind of reported allowance.", "schema": { "enum": [ "rps", "daily", "monthly", "window" ], "type": "string" } } }, "responses": { "OmnapiCustomerRateLimited": { "content": { "application/json": { "examples": { "customer": { "value": { "error": { "code": "RATE_LIMITED", "details": { "current": 6, "limit": 5, "policy": "operation", "retryAfterSec": 1, "scope": "user", "type": "rps" }, "message": "user operation rps limit exceeded; retry after 1s" }, "success": false } }, "ip": { "value": { "error": { "code": "RATE_LIMITED", "message": "Too many requests" }, "success": false } } }, "schema": { "$ref": "#/components/schemas/OmnapiRateLimitedError" } } }, "description": "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.", "headers": { "Retry-After": { "description": "Seconds before retrying a request-rate rejection. Optional: in-flight task caps do not supply a recovery time.", "schema": { "minimum": 1, "type": "integer" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "OmnapiIpRateLimited": { "content": { "application/json": { "examples": { "ip": { "value": { "error": { "code": "RATE_LIMITED", "message": "Too many requests" }, "success": false } } }, "schema": { "$ref": "#/components/schemas/OmnapiRateLimitedError" } } }, "description": "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.", "headers": { "Retry-After": { "description": "Seconds before retrying a request-rate rejection. Optional: in-flight task caps do not supply a recovery time.", "schema": { "minimum": 1, "type": "integer" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "description": "Public IP protection.", "schema": { "enum": [ "ip" ], "type": "string" } }, "X-RateLimit-Type": { "description": "IP protection window.", "schema": { "enum": [ "window" ], "type": "string" } } } }, "OmnapiTaskRateLimited": { "content": { "application/json": { "examples": { "accountInFlight": { "value": { "error": { "code": "RATE_LIMITED", "details": { "inFlight": 20, "limit": 20, "tier": "FREE" }, "message": "Too many in-flight tasks (20/20). Wait for running tasks to finish before creating more." }, "success": false } }, "customer": { "value": { "error": { "code": "RATE_LIMITED", "details": { "current": 6, "limit": 5, "policy": "operation", "retryAfterSec": 1, "scope": "user", "type": "rps" }, "message": "user operation rps limit exceeded; retry after 1s" }, "success": false } }, "ip": { "value": { "error": { "code": "RATE_LIMITED", "message": "Too many requests" }, "success": false } }, "keyInFlight": { "value": { "error": { "code": "RATE_LIMITED", "details": { "inFlight": 20, "limit": 20, "scope": "apiKey", "tier": "FREE" }, "message": "Too many in-flight tasks for this API key (20/20). Wait for running tasks to finish before creating more." }, "success": false } } }, "schema": { "$ref": "#/components/schemas/OmnapiRateLimitedError" } } }, "description": "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.", "headers": { "Retry-After": { "description": "Seconds before retrying a request-rate rejection. Optional: in-flight task caps do not supply a recovery time.", "schema": { "minimum": 1, "type": "integer" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } } }, "schemas": { "OmnapiRateLimitedError": { "properties": { "error": { "properties": { "code": { "description": "RATE_LIMITED for request and task admission rejections.", "type": "string" }, "details": { "additionalProperties": true, "description": "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.", "patternProperties": { "^(.*)$": {} }, "properties": { "current": { "minimum": 0, "type": "integer" }, "inFlight": { "minimum": 0, "type": "integer" }, "limit": { "minimum": 0, "type": "integer" }, "policy": { "enum": [ "operation", "query" ], "type": "string" }, "retryAfterSec": { "minimum": 1, "type": "integer" }, "scope": { "enum": [ "user", "api-key", "ip", "apiKey" ], "type": "string" }, "tier": { "enum": [ "FREE", "PREMIUM", "ENTERPRISE" ], "type": "string" }, "type": { "enum": [ "rps", "daily", "monthly" ], "type": "string" } }, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "default": false, "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "OmnAPI API key. Send this header on every public API request." } } }, "info": { "description": "Public OpenAPI contract for OmnAPI customer-facing API endpoints.", "title": "OmnAPI - Unified AI Services Platform", "version": "2.0.0" }, "openapi": "3.0.3", "paths": { "/api/v1/account/credits": { "get": { "description": "Returns the caller's exact OmnAPI credit balance from the billing source of truth. Suitable for low-balance monitoring and alerts.", "operationId": "getApiV1AccountCredits", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "balanceCredits": { "description": "Exact currently available OmnAPI credit balance.", "minimum": 0, "type": "number" }, "balanceUnits": { "description": "Exact balance in credit units as a decimal string (1 credit = 10000 units).", "pattern": "^[0-9]+$", "type": "string" }, "billingStatus": { "enum": [ "ACTIVE", "ON_HOLD" ], "type": "string" }, "tier": { "enum": [ "FREE", "PREMIUM", "ENTERPRISE" ], "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "balanceCredits", "balanceUnits", "tier", "billingStatus", "updatedAt" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "Get Account Credits", "tags": [ "Account" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/lyrics/generate": { "post": { "description": "Create a GPT lyrics-generation task, persist it through the unified task pipeline, and wait briefly for the completed result.", "operationId": "postApiV1LyricsGenerate", "parameters": [ { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "examples": [ { "durationSec": 140, "extraGuidance": "避免过于直白的口号式表达，副歌要有一眼记住的hook", "genre": "mandopop, synthpop", "language": "Chinese", "languages": [ "Chinese", "English" ], "mode": "gpt", "mood": "romantic and cinematic", "multilingualMode": "sectioned", "prompt": "写一首关于雨夜重逢的双语情歌，主歌中文，副歌英文，氛围浪漫电影感", "themeKeywords": [ "rain", "neon", "reunion" ], "vocalStyle": "airy female vocal, intimate and emotional" } ], "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "durationSec": { "description": "Target duration in seconds.", "examples": [ 140 ], "maximum": 480, "minimum": 30, "type": "number" }, "explicit": { "description": "Whether explicit language is acceptable.", "type": "boolean" }, "extraGuidance": { "description": "Additional creative guidance or constraints.", "examples": [ "避免过于直白的口号式表达，副歌要有一眼记住的hook" ], "maxLength": 2000, "type": "string" }, "genre": { "examples": [ "mandopop, synthpop" ], "maxLength": 200, "type": "string", "description": "Requested musical genre direction." }, "language": { "description": "Primary lyric language. Use 'auto' to let the model decide.", "examples": [ "Chinese" ], "maxLength": 80, "type": "string" }, "languages": { "items": { "description": "Additional languages to consider for multilingual lyrics.", "maxLength": 80, "type": "string" }, "type": "array", "description": "Additional languages to include or consider." }, "mode": { "const": "gpt", "description": "Lyrics generation mode. GPT is the supported mode.", "type": "string" }, "mood": { "examples": [ "romantic and cinematic" ], "maxLength": 200, "type": "string", "description": "Requested musical or visual mood." }, "multilingualMode": { "enum": [ "auto", "sectioned", "blended", "call_and_response" ], "type": "string", "description": "How multiple lyric languages should be arranged." }, "negativeConstraints": { "items": { "description": "Styles, topics, or tropes to avoid.", "maxLength": 80, "type": "string" }, "type": "array", "description": "Topics, styles, or tropes the output should avoid." }, "perspective": { "enum": [ "first_person", "second_person", "third_person", "mixed" ], "type": "string", "description": "Requested lyric narrative perspective." }, "prompt": { "description": "Core song brief, story, scene, or hook idea.", "examples": [ "写一首关于雨夜重逢的双语情歌，主歌中文，副歌英文，氛围浪漫电影感" ], "maxLength": 2000, "type": "string" }, "structure": { "items": { "description": "Requested section order, e.g. Verse 1, Chorus, Bridge.", "maxLength": 50, "type": "string" }, "type": "array", "description": "Requested lyric section order." }, "themeKeywords": { "description": "Short theme keywords to anchor the lyrics.", "items": { "maxLength": 60, "type": "string" }, "type": "array" }, "vocalStyle": { "examples": [ "airy female vocal, intimate and emotional" ], "maxLength": 200, "type": "string", "description": "Requested vocal performance direction." } }, "required": [ "prompt" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "examples": [ { "durationSec": 140, "extraGuidance": "避免过于直白的口号式表达，副歌要有一眼记住的hook", "genre": "mandopop, synthpop", "language": "Chinese", "languages": [ "Chinese", "English" ], "mode": "gpt", "mood": "romantic and cinematic", "multilingualMode": "sectioned", "prompt": "写一首关于雨夜重逢的双语情歌，主歌中文，副歌英文，氛围浪漫电影感", "themeKeywords": [ "rain", "neon", "reunion" ], "vocalStyle": "airy female vocal, intimate and emotional" } ], "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "durationSec": { "description": "Target duration in seconds.", "examples": [ 140 ], "maximum": 480, "minimum": 30, "type": "number" }, "explicit": { "description": "Whether explicit language is acceptable.", "type": "boolean" }, "extraGuidance": { "description": "Additional creative guidance or constraints.", "examples": [ "避免过于直白的口号式表达，副歌要有一眼记住的hook" ], "maxLength": 2000, "type": "string" }, "genre": { "examples": [ "mandopop, synthpop" ], "maxLength": 200, "type": "string", "description": "Requested musical genre direction." }, "language": { "description": "Primary lyric language. Use 'auto' to let the model decide.", "examples": [ "Chinese" ], "maxLength": 80, "type": "string" }, "languages": { "items": { "description": "Additional languages to consider for multilingual lyrics.", "maxLength": 80, "type": "string" }, "type": "array", "description": "Additional languages to include or consider." }, "mode": { "const": "gpt", "description": "Lyrics generation mode. GPT is the supported mode.", "type": "string" }, "mood": { "examples": [ "romantic and cinematic" ], "maxLength": 200, "type": "string", "description": "Requested musical or visual mood." }, "multilingualMode": { "enum": [ "auto", "sectioned", "blended", "call_and_response" ], "type": "string", "description": "How multiple lyric languages should be arranged." }, "negativeConstraints": { "items": { "description": "Styles, topics, or tropes to avoid.", "maxLength": 80, "type": "string" }, "type": "array", "description": "Topics, styles, or tropes the output should avoid." }, "perspective": { "enum": [ "first_person", "second_person", "third_person", "mixed" ], "type": "string", "description": "Requested lyric narrative perspective." }, "prompt": { "description": "Core song brief, story, scene, or hook idea.", "examples": [ "写一首关于雨夜重逢的双语情歌，主歌中文，副歌英文，氛围浪漫电影感" ], "maxLength": 2000, "type": "string" }, "structure": { "items": { "description": "Requested section order, e.g. Verse 1, Chorus, Bridge.", "maxLength": 50, "type": "string" }, "type": "array", "description": "Requested lyric section order." }, "themeKeywords": { "description": "Short theme keywords to anchor the lyrics.", "items": { "maxLength": 60, "type": "string" }, "type": "array" }, "vocalStyle": { "examples": [ "airy female vocal, intimate and emotional" ], "maxLength": 200, "type": "string", "description": "Requested vocal performance direction." } }, "required": [ "prompt" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "examples": [ { "durationSec": 140, "extraGuidance": "避免过于直白的口号式表达，副歌要有一眼记住的hook", "genre": "mandopop, synthpop", "language": "Chinese", "languages": [ "Chinese", "English" ], "mode": "gpt", "mood": "romantic and cinematic", "multilingualMode": "sectioned", "prompt": "写一首关于雨夜重逢的双语情歌，主歌中文，副歌英文，氛围浪漫电影感", "themeKeywords": [ "rain", "neon", "reunion" ], "vocalStyle": "airy female vocal, intimate and emotional" } ], "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "durationSec": { "description": "Target duration in seconds.", "examples": [ 140 ], "maximum": 480, "minimum": 30, "type": "number" }, "explicit": { "description": "Whether explicit language is acceptable.", "type": "boolean" }, "extraGuidance": { "description": "Additional creative guidance or constraints.", "examples": [ "避免过于直白的口号式表达，副歌要有一眼记住的hook" ], "maxLength": 2000, "type": "string" }, "genre": { "examples": [ "mandopop, synthpop" ], "maxLength": 200, "type": "string", "description": "Requested musical genre direction." }, "language": { "description": "Primary lyric language. Use 'auto' to let the model decide.", "examples": [ "Chinese" ], "maxLength": 80, "type": "string" }, "languages": { "items": { "description": "Additional languages to consider for multilingual lyrics.", "maxLength": 80, "type": "string" }, "type": "array", "description": "Additional languages to include or consider." }, "mode": { "const": "gpt", "description": "Lyrics generation mode. GPT is the supported mode.", "type": "string" }, "mood": { "examples": [ "romantic and cinematic" ], "maxLength": 200, "type": "string", "description": "Requested musical or visual mood." }, "multilingualMode": { "enum": [ "auto", "sectioned", "blended", "call_and_response" ], "type": "string", "description": "How multiple lyric languages should be arranged." }, "negativeConstraints": { "items": { "description": "Styles, topics, or tropes to avoid.", "maxLength": 80, "type": "string" }, "type": "array", "description": "Topics, styles, or tropes the output should avoid." }, "perspective": { "enum": [ "first_person", "second_person", "third_person", "mixed" ], "type": "string", "description": "Requested lyric narrative perspective." }, "prompt": { "description": "Core song brief, story, scene, or hook idea.", "examples": [ "写一首关于雨夜重逢的双语情歌，主歌中文，副歌英文，氛围浪漫电影感" ], "maxLength": 2000, "type": "string" }, "structure": { "items": { "description": "Requested section order, e.g. Verse 1, Chorus, Bridge.", "maxLength": 50, "type": "string" }, "type": "array", "description": "Requested lyric section order." }, "themeKeywords": { "description": "Short theme keywords to anchor the lyrics.", "items": { "maxLength": 60, "type": "string" }, "type": "array" }, "vocalStyle": { "examples": [ "airy female vocal, intimate and emotional" ], "maxLength": 200, "type": "string", "description": "Requested vocal performance direction." } }, "required": [ "prompt" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "examples": [ { "creditsCharged": 12, "hook": "Stay with me in the neon rain tonight", "languagePlan": { "mixStrategy": "Chinese verses with an English chorus hook.", "primaryLanguage": "Chinese", "secondaryLanguages": [ "English" ], "transliteration": null }, "lyrics": "[Verse 1]\n街灯把回忆照亮\n你站在雨里像从前一样\n[Chorus]\nStay with me in the neon rain tonight", "model": "gpt-4.1-mini", "modelPath": "gpt/gpt-4.1-mini/lyrics-generation", "notes": [ "Keep the English chorus clean and easy to repeat.", "Let the Chinese verses carry the story detail." ], "producer": { "lyrics": "[Verse 1]\n街灯把回忆照亮\n你站在雨里像从前一样\n[Chorus]\nStay with me in the neon rain tonight", "soundPrompt": "Romantic mandopop with synthpop sheen, airy female vocal, warm pads, glossy drums, cinematic rain-soaked atmosphere, emotional hook, mid-tempo.", "title": "霓虹雨夜" }, "sectionOrder": [ "Verse 1", "Chorus" ], "suno": { "negativeTags": "heavy metal, aggressive rap", "prompt": "[Verse 1]\n街灯把回忆照亮\n你站在雨里像从前一样\n[Chorus]\nStay with me in the neon rain tonight", "tags": "mandopop, synthpop, romantic, cinematic, neon rain, female vocal, warm pads, glossy drums", "title": "霓虹雨夜" }, "title": "霓虹雨夜", "usage": { "completionTokens": 860, "promptTokens": 520, "totalTokens": 1380 } } ], "properties": { "creditsCharged": { "type": "number" }, "hook": { "type": "string" }, "languagePlan": { "properties": { "mixStrategy": { "type": "string" }, "primaryLanguage": { "type": "string" }, "secondaryLanguages": { "items": { "type": "string" }, "type": "array" }, "transliteration": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true } }, "required": [ "primaryLanguage", "secondaryLanguages", "mixStrategy", "transliteration" ], "type": "object" }, "lyrics": { "type": "string" }, "model": { "type": "string" }, "modelPath": { "type": "string" }, "notes": { "items": { "type": "string" }, "type": "array" }, "producer": { "properties": { "lyrics": { "type": "string" }, "soundPrompt": { "type": "string" }, "title": { "type": "string" } }, "required": [ "title", "lyrics", "soundPrompt" ], "type": "object" }, "sectionOrder": { "items": { "type": "string" }, "type": "array" }, "status": { "const": "COMPLETED", "type": "string" }, "suno": { "properties": { "negativeTags": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "prompt": { "type": "string" }, "tags": { "type": "string" }, "title": { "type": "string" } }, "required": [ "title", "prompt", "tags", "negativeTags" ], "type": "object" }, "taskId": { "type": "string" }, "title": { "type": "string" }, "usage": { "properties": { "completionTokens": { "type": "number" }, "promptTokens": { "type": "number" }, "totalTokens": { "type": "number" } }, "type": "object" } }, "required": [ "taskId", "status", "model", "modelPath", "creditsCharged", "title", "lyrics", "languagePlan", "sectionOrder", "hook", "suno", "producer", "notes" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "202": { "content": { "application/json": { "schema": { "examples": [ { "creditsRequired": 12, "message": "Lyrics task is still processing. Query the task endpoint for the final result.", "modelPath": "gpt/gpt-4.1-mini/lyrics-generation", "pollUrl": "/api/v1/tasks/0195abc0-9fb3-7d12-9b1d-0c5fbbfda123", "status": "PROCESSING", "taskId": "0195abc0-9fb3-7d12-9b1d-0c5fbbfda123" } ], "properties": { "creditsRequired": { "type": "number" }, "message": { "type": "string" }, "modelPath": { "type": "string" }, "pollUrl": { "type": "string" }, "status": { "enum": [ "PENDING", "PROCESSING" ], "type": "string" }, "taskId": { "type": "string" } }, "required": [ "taskId", "status", "modelPath", "creditsRequired", "message", "pollUrl" ], "type": "object" } } }, "description": "Response for status 202", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "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." }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 409" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 502" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Generate Lyrics Package", "tags": [ "Lyrics" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/mv/": { "get": { "description": "Cursor-paginated Fast and Studio MV project history. Archived projects are excluded.", "operationId": "getApiV1Mv", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20, "description": "Maximum MVs to return." } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" }, "description": "Opaque pagination cursor returned as nextCursor; omit it on the first page." } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "hasMore": { "type": "boolean" }, "items": { "items": { "properties": { "createdAt": { "type": "string" }, "generatedSceneVideoCount": { "type": "number" }, "generatedVideoCount": { "type": "number" }, "hasFinalVideo": { "type": "boolean" }, "mode": { "enum": [ "fast", "studio" ], "type": "string" }, "mvId": { "type": "string" }, "sceneCount": { "type": "number" }, "status": { "enum": [ "PENDING", "GENERATING", "ACTION_REQUIRED", "READY", "RENDERING", "FINALIZING", "COMPLETED", "EDITING", "FAILED", "ARCHIVED", "DELETED" ], "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "updatedAt": { "type": "string" } }, "required": [ "mvId", "mode", "title", "status", "hasFinalVideo", "sceneCount", "generatedSceneVideoCount", "generatedVideoCount", "createdAt", "updatedAt" ], "type": "object" }, "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true } }, "required": [ "items", "nextCursor", "hasMore" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "List MVs", "tags": [ "MV" ], "security": [ { "ApiKeyAuth": [] } ] }, "post": { "description": "Create a Fast finished MV or Studio storyboard. The accepted response returns `taskId` and the same value as an immediately stable `mvId` alias, addressable through `viewUrl`; the resolved MVView may later expose the canonical project/storyboard id. Send an `Idempotency-Key` header to make retries safe — a duplicate key replays the original response without charging again. If maxCredits is present, the final create-time quote must not exceed it.", "operationId": "postApiV1Mv", "parameters": [ { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "aspectRatio": { "anyOf": [ { "const": "16:9", "type": "string" }, { "const": "9:16", "type": "string" }, { "const": "1:1", "type": "string" }, { "const": "4:3", "type": "string" }, { "const": "3:4", "type": "string" } ], "description": "Requested output aspect ratio." }, "characterImage": { "minLength": 1, "type": "string", "description": "Public character reference image URL." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "generation": { "additionalProperties": false, "properties": { "creativeMode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "lyrics_story", "type": "string" }, { "const": "prompt_story", "type": "string" }, { "const": "mood_visual", "type": "string" }, { "const": "performance", "type": "string" } ], "description": "Creative intent used by Fast MV prompt and reference planning." }, "lipReferenceImages": { "description": "Ordered Premium V2 singer portrait URLs; the first item maps to the first singer.", "items": { "minLength": 1, "type": "string" }, "maxItems": 2, "minItems": 1, "type": "array" }, "managedVersion": { "anyOf": [ { "const": "oneclick-v1", "type": "string" }, { "const": "premium-v2", "type": "string" } ], "description": "Managed Fast MV engine version. Existing clients default to oneclick-v1; premium-v2 must be selected explicitly." }, "motionPreset": { "anyOf": [ { "const": "stable_performance", "type": "string" }, { "const": "cinematic_light", "type": "string" }, { "const": "dynamic_dance", "type": "string" }, { "const": "lip_sync_closeup", "type": "string" } ], "description": "Fast MV motion prompt policy." }, "performanceMode": { "anyOf": [ { "const": "sing", "type": "string" }, { "const": "sing_perform", "type": "string" }, { "const": "perform", "type": "string" }, { "const": "dance", "type": "string" } ], "description": "Premium V2 performance mode: singing, singing with performance, instrumental performance, or dance." }, "promptMode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "verbatim", "type": "string" }, { "const": "creative_brief", "type": "string" } ], "description": "Whether Fast MV preserves or compiles the caller prompt." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "high", "type": "string" } ], "description": "Requested public quality tier." }, "referenceStrategy": { "anyOf": [ { "const": "direct", "type": "string" }, { "const": "synthesize", "type": "string" } ], "description": "Fast MV policy for direct or synthesized references." }, "style": { "maxLength": 200, "type": "string", "description": "Requested creative style direction." }, "subtitleMode": { "anyOf": [ { "const": "vidu", "type": "string" }, { "const": "custom", "type": "string" } ], "description": "Fast MV subtitle rendering mode." }, "visualBoard": { "additionalProperties": false, "properties": { "imageProvider": { "anyOf": [ { "const": "gpt-image-2", "type": "string" }, { "const": "p-image", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public image-generation option code." }, "preset": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "speed", "type": "string" }, { "const": "detail", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Visual Board speed/detail policy." } }, "type": "object", "description": "Fast MV Visual Board configuration." } }, "type": "object", "description": "Product-specific generation controls." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "lipSync": { "type": "boolean", "description": "Whether the MV should use the supported lip-sync workflow." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "fast", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "preflightId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Reusable MV preflight snapshot identifier." }, "prompt": { "maxLength": 3000, "type": "string", "description": "Primary creative or operation instruction." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "referenceImages": { "items": { "minLength": 1, "type": "string" }, "maxItems": 7, "type": "array", "description": "Public reference image URLs." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "source": { "anyOf": [ { "additionalProperties": false, "properties": { "clipId": { "minLength": 1, "type": "string", "description": "Source clip identifier." }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "suno", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "clipId" ], "type": "object" }, { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "description": "Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.", "exclusiveMinimum": 0, "type": "number" }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object" } ], "description": "Public source media or product reference." }, "srtUrl": { "minLength": 1, "type": "string", "description": "Public URL of caller-supplied SRT subtitles." }, "subtitle": { "additionalProperties": false, "properties": { "fallback": { "anyOf": [ { "const": "fail", "type": "string" }, { "const": "continue_without_subtitles", "type": "string" } ], "description": "Behavior when the preferred subtitle path cannot complete." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." }, "mode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "provided", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Operation or product mode discriminator for this schema variant." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "premium", "type": "string" } ], "description": "Requested public quality tier." }, "required": { "type": "boolean", "description": "Whether the selected subtitle policy must succeed." } }, "type": "object", "description": "MV subtitle generation and fallback policy." }, "subtitleColor": { "maxLength": 20, "type": "string", "description": "Requested subtitle foreground color." }, "subtitles": { "type": "boolean", "description": "Whether subtitles are enabled for the MV." }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "mode", "source" ], "type": "object" }, { "additionalProperties": false, "properties": { "aspectRatio": { "anyOf": [ { "const": "16:9", "type": "string" }, { "const": "9:16", "type": "string" }, { "const": "1:1", "type": "string" }, { "const": "4:3", "type": "string" }, { "const": "3:4", "type": "string" } ], "description": "Requested output aspect ratio." }, "characterImage": { "minLength": 1, "type": "string", "description": "Public character reference image URL." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "generation": { "additionalProperties": false, "properties": { "imageProvider": { "anyOf": [ { "const": "p-image", "type": "string" }, { "const": "gpt-image-2", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public image-generation option code." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoProvider": { "anyOf": [ { "const": "p-video", "type": "string" }, { "const": "hailuo", "type": "string" }, { "const": "vidu", "type": "string" } ], "description": "Public scene-video option code." } }, "type": "object", "description": "Product-specific generation controls." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "lipSync": { "type": "boolean", "description": "Whether the MV should use the supported lip-sync workflow." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "preflightId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Reusable MV preflight snapshot identifier." }, "prompt": { "maxLength": 3000, "type": "string", "description": "Primary creative or operation instruction." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "referenceImages": { "items": { "minLength": 1, "type": "string" }, "maxItems": 7, "type": "array", "description": "Public reference image URLs." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "source": { "anyOf": [ { "additionalProperties": false, "properties": { "clipId": { "minLength": 1, "type": "string", "description": "Source clip identifier." }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "suno", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "clipId" ], "type": "object" }, { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "description": "Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.", "exclusiveMinimum": 0, "type": "number" }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object" } ], "description": "Public source media or product reference." }, "srtUrl": { "minLength": 1, "type": "string", "description": "Public URL of caller-supplied SRT subtitles." }, "subtitle": { "additionalProperties": false, "properties": { "fallback": { "anyOf": [ { "const": "fail", "type": "string" }, { "const": "continue_without_subtitles", "type": "string" } ], "description": "Behavior when the preferred subtitle path cannot complete." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." }, "mode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "provided", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Operation or product mode discriminator for this schema variant." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "premium", "type": "string" } ], "description": "Requested public quality tier." }, "required": { "type": "boolean", "description": "Whether the selected subtitle policy must succeed." } }, "type": "object", "description": "MV subtitle generation and fallback policy." }, "subtitleColor": { "maxLength": 20, "type": "string", "description": "Requested subtitle foreground color." }, "subtitles": { "type": "boolean", "description": "Whether subtitles are enabled for the MV." }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "mode", "source" ], "type": "object" } ] } }, "application/x-www-form-urlencoded": { "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "aspectRatio": { "anyOf": [ { "const": "16:9", "type": "string" }, { "const": "9:16", "type": "string" }, { "const": "1:1", "type": "string" }, { "const": "4:3", "type": "string" }, { "const": "3:4", "type": "string" } ], "description": "Requested output aspect ratio." }, "characterImage": { "minLength": 1, "type": "string", "description": "Public character reference image URL." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "generation": { "additionalProperties": false, "properties": { "creativeMode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "lyrics_story", "type": "string" }, { "const": "prompt_story", "type": "string" }, { "const": "mood_visual", "type": "string" }, { "const": "performance", "type": "string" } ], "description": "Creative intent used by Fast MV prompt and reference planning." }, "lipReferenceImages": { "description": "Ordered Premium V2 singer portrait URLs; the first item maps to the first singer.", "items": { "minLength": 1, "type": "string" }, "maxItems": 2, "minItems": 1, "type": "array" }, "managedVersion": { "anyOf": [ { "const": "oneclick-v1", "type": "string" }, { "const": "premium-v2", "type": "string" } ], "description": "Managed Fast MV engine version. Existing clients default to oneclick-v1; premium-v2 must be selected explicitly." }, "motionPreset": { "anyOf": [ { "const": "stable_performance", "type": "string" }, { "const": "cinematic_light", "type": "string" }, { "const": "dynamic_dance", "type": "string" }, { "const": "lip_sync_closeup", "type": "string" } ], "description": "Fast MV motion prompt policy." }, "performanceMode": { "anyOf": [ { "const": "sing", "type": "string" }, { "const": "sing_perform", "type": "string" }, { "const": "perform", "type": "string" }, { "const": "dance", "type": "string" } ], "description": "Premium V2 performance mode: singing, singing with performance, instrumental performance, or dance." }, "promptMode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "verbatim", "type": "string" }, { "const": "creative_brief", "type": "string" } ], "description": "Whether Fast MV preserves or compiles the caller prompt." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "high", "type": "string" } ], "description": "Requested public quality tier." }, "referenceStrategy": { "anyOf": [ { "const": "direct", "type": "string" }, { "const": "synthesize", "type": "string" } ], "description": "Fast MV policy for direct or synthesized references." }, "style": { "maxLength": 200, "type": "string", "description": "Requested creative style direction." }, "subtitleMode": { "anyOf": [ { "const": "vidu", "type": "string" }, { "const": "custom", "type": "string" } ], "description": "Fast MV subtitle rendering mode." }, "visualBoard": { "additionalProperties": false, "properties": { "imageProvider": { "anyOf": [ { "const": "gpt-image-2", "type": "string" }, { "const": "p-image", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public image-generation option code." }, "preset": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "speed", "type": "string" }, { "const": "detail", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Visual Board speed/detail policy." } }, "type": "object", "description": "Fast MV Visual Board configuration." } }, "type": "object", "description": "Product-specific generation controls." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "lipSync": { "type": "boolean", "description": "Whether the MV should use the supported lip-sync workflow." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "fast", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "preflightId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Reusable MV preflight snapshot identifier." }, "prompt": { "maxLength": 3000, "type": "string", "description": "Primary creative or operation instruction." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "referenceImages": { "items": { "minLength": 1, "type": "string" }, "maxItems": 7, "type": "array", "description": "Public reference image URLs." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "source": { "anyOf": [ { "additionalProperties": false, "properties": { "clipId": { "minLength": 1, "type": "string", "description": "Source clip identifier." }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "suno", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "clipId" ], "type": "object" }, { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "description": "Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.", "exclusiveMinimum": 0, "type": "number" }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object" } ], "description": "Public source media or product reference." }, "srtUrl": { "minLength": 1, "type": "string", "description": "Public URL of caller-supplied SRT subtitles." }, "subtitle": { "additionalProperties": false, "properties": { "fallback": { "anyOf": [ { "const": "fail", "type": "string" }, { "const": "continue_without_subtitles", "type": "string" } ], "description": "Behavior when the preferred subtitle path cannot complete." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." }, "mode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "provided", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Operation or product mode discriminator for this schema variant." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "premium", "type": "string" } ], "description": "Requested public quality tier." }, "required": { "type": "boolean", "description": "Whether the selected subtitle policy must succeed." } }, "type": "object", "description": "MV subtitle generation and fallback policy." }, "subtitleColor": { "maxLength": 20, "type": "string", "description": "Requested subtitle foreground color." }, "subtitles": { "type": "boolean", "description": "Whether subtitles are enabled for the MV." }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "mode", "source" ], "type": "object" }, { "additionalProperties": false, "properties": { "aspectRatio": { "anyOf": [ { "const": "16:9", "type": "string" }, { "const": "9:16", "type": "string" }, { "const": "1:1", "type": "string" }, { "const": "4:3", "type": "string" }, { "const": "3:4", "type": "string" } ], "description": "Requested output aspect ratio." }, "characterImage": { "minLength": 1, "type": "string", "description": "Public character reference image URL." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "generation": { "additionalProperties": false, "properties": { "imageProvider": { "anyOf": [ { "const": "p-image", "type": "string" }, { "const": "gpt-image-2", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public image-generation option code." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoProvider": { "anyOf": [ { "const": "p-video", "type": "string" }, { "const": "hailuo", "type": "string" }, { "const": "vidu", "type": "string" } ], "description": "Public scene-video option code." } }, "type": "object", "description": "Product-specific generation controls." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "lipSync": { "type": "boolean", "description": "Whether the MV should use the supported lip-sync workflow." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "preflightId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Reusable MV preflight snapshot identifier." }, "prompt": { "maxLength": 3000, "type": "string", "description": "Primary creative or operation instruction." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "referenceImages": { "items": { "minLength": 1, "type": "string" }, "maxItems": 7, "type": "array", "description": "Public reference image URLs." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "source": { "anyOf": [ { "additionalProperties": false, "properties": { "clipId": { "minLength": 1, "type": "string", "description": "Source clip identifier." }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "suno", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "clipId" ], "type": "object" }, { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "description": "Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.", "exclusiveMinimum": 0, "type": "number" }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object" } ], "description": "Public source media or product reference." }, "srtUrl": { "minLength": 1, "type": "string", "description": "Public URL of caller-supplied SRT subtitles." }, "subtitle": { "additionalProperties": false, "properties": { "fallback": { "anyOf": [ { "const": "fail", "type": "string" }, { "const": "continue_without_subtitles", "type": "string" } ], "description": "Behavior when the preferred subtitle path cannot complete." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." }, "mode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "provided", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Operation or product mode discriminator for this schema variant." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "premium", "type": "string" } ], "description": "Requested public quality tier." }, "required": { "type": "boolean", "description": "Whether the selected subtitle policy must succeed." } }, "type": "object", "description": "MV subtitle generation and fallback policy." }, "subtitleColor": { "maxLength": 20, "type": "string", "description": "Requested subtitle foreground color." }, "subtitles": { "type": "boolean", "description": "Whether subtitles are enabled for the MV." }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "mode", "source" ], "type": "object" } ] } }, "multipart/form-data": { "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "aspectRatio": { "anyOf": [ { "const": "16:9", "type": "string" }, { "const": "9:16", "type": "string" }, { "const": "1:1", "type": "string" }, { "const": "4:3", "type": "string" }, { "const": "3:4", "type": "string" } ], "description": "Requested output aspect ratio." }, "characterImage": { "minLength": 1, "type": "string", "description": "Public character reference image URL." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "generation": { "additionalProperties": false, "properties": { "creativeMode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "lyrics_story", "type": "string" }, { "const": "prompt_story", "type": "string" }, { "const": "mood_visual", "type": "string" }, { "const": "performance", "type": "string" } ], "description": "Creative intent used by Fast MV prompt and reference planning." }, "lipReferenceImages": { "description": "Ordered Premium V2 singer portrait URLs; the first item maps to the first singer.", "items": { "minLength": 1, "type": "string" }, "maxItems": 2, "minItems": 1, "type": "array" }, "managedVersion": { "anyOf": [ { "const": "oneclick-v1", "type": "string" }, { "const": "premium-v2", "type": "string" } ], "description": "Managed Fast MV engine version. Existing clients default to oneclick-v1; premium-v2 must be selected explicitly." }, "motionPreset": { "anyOf": [ { "const": "stable_performance", "type": "string" }, { "const": "cinematic_light", "type": "string" }, { "const": "dynamic_dance", "type": "string" }, { "const": "lip_sync_closeup", "type": "string" } ], "description": "Fast MV motion prompt policy." }, "performanceMode": { "anyOf": [ { "const": "sing", "type": "string" }, { "const": "sing_perform", "type": "string" }, { "const": "perform", "type": "string" }, { "const": "dance", "type": "string" } ], "description": "Premium V2 performance mode: singing, singing with performance, instrumental performance, or dance." }, "promptMode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "verbatim", "type": "string" }, { "const": "creative_brief", "type": "string" } ], "description": "Whether Fast MV preserves or compiles the caller prompt." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "high", "type": "string" } ], "description": "Requested public quality tier." }, "referenceStrategy": { "anyOf": [ { "const": "direct", "type": "string" }, { "const": "synthesize", "type": "string" } ], "description": "Fast MV policy for direct or synthesized references." }, "style": { "maxLength": 200, "type": "string", "description": "Requested creative style direction." }, "subtitleMode": { "anyOf": [ { "const": "vidu", "type": "string" }, { "const": "custom", "type": "string" } ], "description": "Fast MV subtitle rendering mode." }, "visualBoard": { "additionalProperties": false, "properties": { "imageProvider": { "anyOf": [ { "const": "gpt-image-2", "type": "string" }, { "const": "p-image", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public image-generation option code." }, "preset": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "speed", "type": "string" }, { "const": "detail", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Visual Board speed/detail policy." } }, "type": "object", "description": "Fast MV Visual Board configuration." } }, "type": "object", "description": "Product-specific generation controls." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "lipSync": { "type": "boolean", "description": "Whether the MV should use the supported lip-sync workflow." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "fast", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "preflightId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Reusable MV preflight snapshot identifier." }, "prompt": { "maxLength": 3000, "type": "string", "description": "Primary creative or operation instruction." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "referenceImages": { "items": { "minLength": 1, "type": "string" }, "maxItems": 7, "type": "array", "description": "Public reference image URLs." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "source": { "anyOf": [ { "additionalProperties": false, "properties": { "clipId": { "minLength": 1, "type": "string", "description": "Source clip identifier." }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "suno", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "clipId" ], "type": "object" }, { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "description": "Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.", "exclusiveMinimum": 0, "type": "number" }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object" } ], "description": "Public source media or product reference." }, "srtUrl": { "minLength": 1, "type": "string", "description": "Public URL of caller-supplied SRT subtitles." }, "subtitle": { "additionalProperties": false, "properties": { "fallback": { "anyOf": [ { "const": "fail", "type": "string" }, { "const": "continue_without_subtitles", "type": "string" } ], "description": "Behavior when the preferred subtitle path cannot complete." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." }, "mode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "provided", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Operation or product mode discriminator for this schema variant." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "premium", "type": "string" } ], "description": "Requested public quality tier." }, "required": { "type": "boolean", "description": "Whether the selected subtitle policy must succeed." } }, "type": "object", "description": "MV subtitle generation and fallback policy." }, "subtitleColor": { "maxLength": 20, "type": "string", "description": "Requested subtitle foreground color." }, "subtitles": { "type": "boolean", "description": "Whether subtitles are enabled for the MV." }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "mode", "source" ], "type": "object" }, { "additionalProperties": false, "properties": { "aspectRatio": { "anyOf": [ { "const": "16:9", "type": "string" }, { "const": "9:16", "type": "string" }, { "const": "1:1", "type": "string" }, { "const": "4:3", "type": "string" }, { "const": "3:4", "type": "string" } ], "description": "Requested output aspect ratio." }, "characterImage": { "minLength": 1, "type": "string", "description": "Public character reference image URL." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "generation": { "additionalProperties": false, "properties": { "imageProvider": { "anyOf": [ { "const": "p-image", "type": "string" }, { "const": "gpt-image-2", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public image-generation option code." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoProvider": { "anyOf": [ { "const": "p-video", "type": "string" }, { "const": "hailuo", "type": "string" }, { "const": "vidu", "type": "string" } ], "description": "Public scene-video option code." } }, "type": "object", "description": "Product-specific generation controls." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "lipSync": { "type": "boolean", "description": "Whether the MV should use the supported lip-sync workflow." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "preflightId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Reusable MV preflight snapshot identifier." }, "prompt": { "maxLength": 3000, "type": "string", "description": "Primary creative or operation instruction." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "referenceImages": { "items": { "minLength": 1, "type": "string" }, "maxItems": 7, "type": "array", "description": "Public reference image URLs." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "source": { "anyOf": [ { "additionalProperties": false, "properties": { "clipId": { "minLength": 1, "type": "string", "description": "Source clip identifier." }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "suno", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "clipId" ], "type": "object" }, { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "description": "Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.", "exclusiveMinimum": 0, "type": "number" }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object" } ], "description": "Public source media or product reference." }, "srtUrl": { "minLength": 1, "type": "string", "description": "Public URL of caller-supplied SRT subtitles." }, "subtitle": { "additionalProperties": false, "properties": { "fallback": { "anyOf": [ { "const": "fail", "type": "string" }, { "const": "continue_without_subtitles", "type": "string" } ], "description": "Behavior when the preferred subtitle path cannot complete." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." }, "mode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "provided", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Operation or product mode discriminator for this schema variant." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "premium", "type": "string" } ], "description": "Requested public quality tier." }, "required": { "type": "boolean", "description": "Whether the selected subtitle policy must succeed." } }, "type": "object", "description": "MV subtitle generation and fallback policy." }, "subtitleColor": { "maxLength": 20, "type": "string", "description": "Requested subtitle foreground color." }, "subtitles": { "type": "boolean", "description": "Whether subtitles are enabled for the MV." }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "mode", "source" ], "type": "object" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "autoFinalize": { "type": "boolean" }, "creditsRequired": { "minimum": 0, "type": "number" }, "deliveryStatus": { "enum": [ "drafting", "incomplete", "rendering", "packaging", "ready", "failed" ], "type": "string" }, "estimatedCompletionTime": { "anyOf": [ { "anyOf": [ { "description": "Estimated completion time", "type": "Date" }, { "format": "date-time", "type": "string" }, { "format": "date", "type": "string" }, { "type": "number" } ], "description": "Estimated completion time" }, { "type": "null" } ], "nullable": true }, "finalUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "links": { "additionalProperties": false, "properties": { "final": { "anyOf": [ { "description": "Final downloadable resource URL when available", "type": "string" }, { "type": "null" } ], "nullable": true }, "resource": { "anyOf": [ { "description": "Product resource URL when the product has a dedicated view endpoint", "type": "string" }, { "type": "null" } ], "nullable": true }, "stream": { "description": "Task SSE stream URL for the created task", "type": "string" }, "task": { "description": "Task polling URL for the created task", "type": "string" } }, "required": [ "task", "stream", "resource", "final" ], "type": "object" }, "mode": { "enum": [ "fast", "studio" ], "type": "string" }, "mvId": { "type": "string" }, "pollUrl": { "type": "string" }, "pricing": { "additionalProperties": false, "properties": { "adjustmentCredits": { "description": "chargedCredits - baseCredits", "type": "number" }, "baseCredits": { "description": "Standard quoted credits before customer pricing adjustment", "type": "number" }, "billingIncrementCredits": { "description": "Smallest customer charge increment", "minimum": 0.0001, "type": "number" }, "calculatedCredits": { "description": "Precise whole-order subtotal before settlement rounding", "type": "number" }, "chargedCredits": { "description": "Credits charged for this create request", "minimum": 0, "type": "number" }, "quoteVersion": { "description": "Pricing quote version stored with the task", "type": "number" }, "settlementPolicyVersion": { "description": "Versioned customer settlement policy", "type": "string" }, "settlementRoundingCredits": { "description": "Whole-order rounding adjustment added at settlement", "minimum": 0, "type": "number" }, "source": { "enum": [ "standard", "customer_rule" ], "type": "string" } }, "required": [ "baseCredits", "chargedCredits", "adjustmentCredits", "source", "quoteVersion" ], "type": "object" }, "product": { "additionalProperties": false, "properties": { "autoFinalize": { "description": "Whether the product should finalize automatically", "type": "boolean" }, "deliveryStatus": { "anyOf": [ { "description": "Product-level delivery status when applicable", "type": "string" }, { "type": "null" } ], "nullable": true }, "featureCode": { "description": "Resolved feature code", "type": "string" }, "modelCode": { "description": "Resolved model code", "type": "string" }, "providerCode": { "description": "Resolved provider code", "type": "string" }, "resourceId": { "anyOf": [ { "description": "Product resource id when created synchronously", "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "description": "Product family for this task, e.g. suno, producer, mv", "type": "string" } }, "required": [ "type", "providerCode", "modelCode", "featureCode", "resourceId" ], "type": "object" }, "requestId": { "anyOf": [ { "description": "Request id echoed from X-Request-Id or generated by API", "type": "string" }, { "type": "null" } ], "nullable": true }, "status": { "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "type": "string" }, "viewUrl": { "type": "string" }, "warningCodes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "mode", "taskId", "status", "creditsRequired", "requestId", "links", "pricing", "product", "warningCodes", "mvId", "pollUrl", "viewUrl", "finalUrl", "autoFinalize", "deliveryStatus" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403 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." }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 409" }, "413": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 413" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 502" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Create MV", "tags": [ "MV" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/mv/fast/availability": { "get": { "description": "Check whether Fast MV creation is currently available. Use the requested managedVersion and honor retryAfterSec before trying again. `gateEnabled` remains in the public contract and is fixed to true; `unknown` and `unavailable` block paid creates before direct debit.", "operationId": "getApiV1MvFastAvailability", "parameters": [ { "in": "query", "name": "managedVersion", "required": false, "schema": { "description": "Managed Fast MV engine version whose commercial availability should be checked.", "enum": [ "oneclick-v1", "premium-v2" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "admissionState": { "enum": [ "AVAILABLE", "DEGRADED", "BACKPRESSURED", "UNAVAILABLE" ], "type": "string" }, "checkedAt": { "type": "string" }, "checks": { "items": { "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "status": { "enum": [ "pass", "warn", "fail", "unknown" ], "type": "string" } }, "required": [ "name", "status", "message" ], "type": "object" }, "type": "array" }, "gateEnabled": { "const": true, "description": "Paid-create availability gate; fixed to true in the current public contract.", "type": "boolean" }, "guidance": { "type": "string" }, "managedVersion": { "enum": [ "oneclick-v1", "premium-v2" ], "type": "string" }, "message": { "type": "string" }, "metrics": { "properties": { "avgTerminalDurationSec": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "failedCount": { "type": "number" }, "failureRate": { "type": "number" }, "predictedDeliveryWaitSec": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "predictedQueueWaitSec": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "processingCount": { "type": "number" }, "projectCount": { "type": "number" }, "readyCount": { "type": "number" }, "readyRate": { "type": "number" }, "recentServiceRatePerMinute": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "staleProcessingCount": { "type": "number" }, "terminalCount": { "type": "number" } }, "required": [ "projectCount", "terminalCount", "readyCount", "failedCount", "processingCount", "staleProcessingCount", "readyRate", "failureRate", "avgTerminalDurationSec", "recentServiceRatePerMinute", "predictedQueueWaitSec", "predictedDeliveryWaitSec" ], "type": "object" }, "retryAfterSec": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "status": { "enum": [ "available", "degraded", "unavailable", "unknown" ], "type": "string" }, "windowMinutes": { "type": "number" } }, "required": [ "managedVersion", "status", "admissionState", "gateEnabled", "checkedAt", "windowMinutes", "retryAfterSec", "message", "guidance", "metrics", "checks" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "Get Fast MV availability", "tags": [ "MV" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/mv/preflight": { "post": { "description": "Validate MV create resources and return a reusable create-time estimate without creating a task or charging credits. The returned preflightId may be supplied to POST /api/v1/mv with the same media and generation body to reuse the validated snapshot. Create-time quoteId and maxCredits may be added or changed without invalidating media validation; final credits are determined immediately before task creation and maxCredits caps the authorized charge.", "operationId": "postApiV1MvPreflight", "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "aspectRatio": { "anyOf": [ { "const": "16:9", "type": "string" }, { "const": "9:16", "type": "string" }, { "const": "1:1", "type": "string" }, { "const": "4:3", "type": "string" }, { "const": "3:4", "type": "string" } ], "description": "Requested output aspect ratio." }, "characterImage": { "minLength": 1, "type": "string", "description": "Public character reference image URL." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "generation": { "additionalProperties": false, "properties": { "creativeMode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "lyrics_story", "type": "string" }, { "const": "prompt_story", "type": "string" }, { "const": "mood_visual", "type": "string" }, { "const": "performance", "type": "string" } ], "description": "Creative intent used by Fast MV prompt and reference planning." }, "lipReferenceImages": { "description": "Ordered Premium V2 singer portrait URLs; the first item maps to the first singer.", "items": { "minLength": 1, "type": "string" }, "maxItems": 2, "minItems": 1, "type": "array" }, "managedVersion": { "anyOf": [ { "const": "oneclick-v1", "type": "string" }, { "const": "premium-v2", "type": "string" } ], "description": "Managed Fast MV engine version. Existing clients default to oneclick-v1; premium-v2 must be selected explicitly." }, "motionPreset": { "anyOf": [ { "const": "stable_performance", "type": "string" }, { "const": "cinematic_light", "type": "string" }, { "const": "dynamic_dance", "type": "string" }, { "const": "lip_sync_closeup", "type": "string" } ], "description": "Fast MV motion prompt policy." }, "performanceMode": { "anyOf": [ { "const": "sing", "type": "string" }, { "const": "sing_perform", "type": "string" }, { "const": "perform", "type": "string" }, { "const": "dance", "type": "string" } ], "description": "Premium V2 performance mode: singing, singing with performance, instrumental performance, or dance." }, "promptMode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "verbatim", "type": "string" }, { "const": "creative_brief", "type": "string" } ], "description": "Whether Fast MV preserves or compiles the caller prompt." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "high", "type": "string" } ], "description": "Requested public quality tier." }, "referenceStrategy": { "anyOf": [ { "const": "direct", "type": "string" }, { "const": "synthesize", "type": "string" } ], "description": "Fast MV policy for direct or synthesized references." }, "style": { "maxLength": 200, "type": "string", "description": "Requested creative style direction." }, "subtitleMode": { "anyOf": [ { "const": "vidu", "type": "string" }, { "const": "custom", "type": "string" } ], "description": "Fast MV subtitle rendering mode." }, "visualBoard": { "additionalProperties": false, "properties": { "imageProvider": { "anyOf": [ { "const": "gpt-image-2", "type": "string" }, { "const": "p-image", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public image-generation option code." }, "preset": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "speed", "type": "string" }, { "const": "detail", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Visual Board speed/detail policy." } }, "type": "object", "description": "Fast MV Visual Board configuration." } }, "type": "object", "description": "Product-specific generation controls." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "lipSync": { "type": "boolean", "description": "Whether the MV should use the supported lip-sync workflow." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "fast", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "prompt": { "maxLength": 3000, "type": "string", "description": "Primary creative or operation instruction." }, "referenceImages": { "items": { "minLength": 1, "type": "string" }, "maxItems": 7, "type": "array", "description": "Public reference image URLs." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "source": { "anyOf": [ { "additionalProperties": false, "properties": { "clipId": { "minLength": 1, "type": "string", "description": "Source clip identifier." }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "suno", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "clipId" ], "type": "object" }, { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "description": "Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.", "exclusiveMinimum": 0, "type": "number" }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object" } ], "description": "Public source media or product reference." }, "srtUrl": { "minLength": 1, "type": "string", "description": "Public URL of caller-supplied SRT subtitles." }, "subtitle": { "additionalProperties": false, "properties": { "fallback": { "anyOf": [ { "const": "fail", "type": "string" }, { "const": "continue_without_subtitles", "type": "string" } ], "description": "Behavior when the preferred subtitle path cannot complete." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." }, "mode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "provided", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Operation or product mode discriminator for this schema variant." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "premium", "type": "string" } ], "description": "Requested public quality tier." }, "required": { "type": "boolean", "description": "Whether the selected subtitle policy must succeed." } }, "type": "object", "description": "MV subtitle generation and fallback policy." }, "subtitleColor": { "maxLength": 20, "type": "string", "description": "Requested subtitle foreground color." }, "subtitles": { "type": "boolean", "description": "Whether subtitles are enabled for the MV." }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "mode", "source" ], "type": "object" }, { "additionalProperties": false, "properties": { "aspectRatio": { "anyOf": [ { "const": "16:9", "type": "string" }, { "const": "9:16", "type": "string" }, { "const": "1:1", "type": "string" }, { "const": "4:3", "type": "string" }, { "const": "3:4", "type": "string" } ], "description": "Requested output aspect ratio." }, "characterImage": { "minLength": 1, "type": "string", "description": "Public character reference image URL." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "generation": { "additionalProperties": false, "properties": { "imageProvider": { "anyOf": [ { "const": "p-image", "type": "string" }, { "const": "gpt-image-2", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public image-generation option code." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoProvider": { "anyOf": [ { "const": "p-video", "type": "string" }, { "const": "hailuo", "type": "string" }, { "const": "vidu", "type": "string" } ], "description": "Public scene-video option code." } }, "type": "object", "description": "Product-specific generation controls." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "lipSync": { "type": "boolean", "description": "Whether the MV should use the supported lip-sync workflow." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "prompt": { "maxLength": 3000, "type": "string", "description": "Primary creative or operation instruction." }, "referenceImages": { "items": { "minLength": 1, "type": "string" }, "maxItems": 7, "type": "array", "description": "Public reference image URLs." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "source": { "anyOf": [ { "additionalProperties": false, "properties": { "clipId": { "minLength": 1, "type": "string", "description": "Source clip identifier." }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "suno", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "clipId" ], "type": "object" }, { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "description": "Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.", "exclusiveMinimum": 0, "type": "number" }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object" } ], "description": "Public source media or product reference." }, "srtUrl": { "minLength": 1, "type": "string", "description": "Public URL of caller-supplied SRT subtitles." }, "subtitle": { "additionalProperties": false, "properties": { "fallback": { "anyOf": [ { "const": "fail", "type": "string" }, { "const": "continue_without_subtitles", "type": "string" } ], "description": "Behavior when the preferred subtitle path cannot complete." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." }, "mode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "provided", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Operation or product mode discriminator for this schema variant." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "premium", "type": "string" } ], "description": "Requested public quality tier." }, "required": { "type": "boolean", "description": "Whether the selected subtitle policy must succeed." } }, "type": "object", "description": "MV subtitle generation and fallback policy." }, "subtitleColor": { "maxLength": 20, "type": "string", "description": "Requested subtitle foreground color." }, "subtitles": { "type": "boolean", "description": "Whether subtitles are enabled for the MV." }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "mode", "source" ], "type": "object" } ] } }, "application/x-www-form-urlencoded": { "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "aspectRatio": { "anyOf": [ { "const": "16:9", "type": "string" }, { "const": "9:16", "type": "string" }, { "const": "1:1", "type": "string" }, { "const": "4:3", "type": "string" }, { "const": "3:4", "type": "string" } ], "description": "Requested output aspect ratio." }, "characterImage": { "minLength": 1, "type": "string", "description": "Public character reference image URL." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "generation": { "additionalProperties": false, "properties": { "creativeMode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "lyrics_story", "type": "string" }, { "const": "prompt_story", "type": "string" }, { "const": "mood_visual", "type": "string" }, { "const": "performance", "type": "string" } ], "description": "Creative intent used by Fast MV prompt and reference planning." }, "lipReferenceImages": { "description": "Ordered Premium V2 singer portrait URLs; the first item maps to the first singer.", "items": { "minLength": 1, "type": "string" }, "maxItems": 2, "minItems": 1, "type": "array" }, "managedVersion": { "anyOf": [ { "const": "oneclick-v1", "type": "string" }, { "const": "premium-v2", "type": "string" } ], "description": "Managed Fast MV engine version. Existing clients default to oneclick-v1; premium-v2 must be selected explicitly." }, "motionPreset": { "anyOf": [ { "const": "stable_performance", "type": "string" }, { "const": "cinematic_light", "type": "string" }, { "const": "dynamic_dance", "type": "string" }, { "const": "lip_sync_closeup", "type": "string" } ], "description": "Fast MV motion prompt policy." }, "performanceMode": { "anyOf": [ { "const": "sing", "type": "string" }, { "const": "sing_perform", "type": "string" }, { "const": "perform", "type": "string" }, { "const": "dance", "type": "string" } ], "description": "Premium V2 performance mode: singing, singing with performance, instrumental performance, or dance." }, "promptMode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "verbatim", "type": "string" }, { "const": "creative_brief", "type": "string" } ], "description": "Whether Fast MV preserves or compiles the caller prompt." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "high", "type": "string" } ], "description": "Requested public quality tier." }, "referenceStrategy": { "anyOf": [ { "const": "direct", "type": "string" }, { "const": "synthesize", "type": "string" } ], "description": "Fast MV policy for direct or synthesized references." }, "style": { "maxLength": 200, "type": "string", "description": "Requested creative style direction." }, "subtitleMode": { "anyOf": [ { "const": "vidu", "type": "string" }, { "const": "custom", "type": "string" } ], "description": "Fast MV subtitle rendering mode." }, "visualBoard": { "additionalProperties": false, "properties": { "imageProvider": { "anyOf": [ { "const": "gpt-image-2", "type": "string" }, { "const": "p-image", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public image-generation option code." }, "preset": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "speed", "type": "string" }, { "const": "detail", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Visual Board speed/detail policy." } }, "type": "object", "description": "Fast MV Visual Board configuration." } }, "type": "object", "description": "Product-specific generation controls." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "lipSync": { "type": "boolean", "description": "Whether the MV should use the supported lip-sync workflow." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "fast", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "prompt": { "maxLength": 3000, "type": "string", "description": "Primary creative or operation instruction." }, "referenceImages": { "items": { "minLength": 1, "type": "string" }, "maxItems": 7, "type": "array", "description": "Public reference image URLs." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "source": { "anyOf": [ { "additionalProperties": false, "properties": { "clipId": { "minLength": 1, "type": "string", "description": "Source clip identifier." }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "suno", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "clipId" ], "type": "object" }, { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "description": "Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.", "exclusiveMinimum": 0, "type": "number" }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object" } ], "description": "Public source media or product reference." }, "srtUrl": { "minLength": 1, "type": "string", "description": "Public URL of caller-supplied SRT subtitles." }, "subtitle": { "additionalProperties": false, "properties": { "fallback": { "anyOf": [ { "const": "fail", "type": "string" }, { "const": "continue_without_subtitles", "type": "string" } ], "description": "Behavior when the preferred subtitle path cannot complete." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." }, "mode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "provided", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Operation or product mode discriminator for this schema variant." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "premium", "type": "string" } ], "description": "Requested public quality tier." }, "required": { "type": "boolean", "description": "Whether the selected subtitle policy must succeed." } }, "type": "object", "description": "MV subtitle generation and fallback policy." }, "subtitleColor": { "maxLength": 20, "type": "string", "description": "Requested subtitle foreground color." }, "subtitles": { "type": "boolean", "description": "Whether subtitles are enabled for the MV." }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "mode", "source" ], "type": "object" }, { "additionalProperties": false, "properties": { "aspectRatio": { "anyOf": [ { "const": "16:9", "type": "string" }, { "const": "9:16", "type": "string" }, { "const": "1:1", "type": "string" }, { "const": "4:3", "type": "string" }, { "const": "3:4", "type": "string" } ], "description": "Requested output aspect ratio." }, "characterImage": { "minLength": 1, "type": "string", "description": "Public character reference image URL." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "generation": { "additionalProperties": false, "properties": { "imageProvider": { "anyOf": [ { "const": "p-image", "type": "string" }, { "const": "gpt-image-2", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public image-generation option code." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoProvider": { "anyOf": [ { "const": "p-video", "type": "string" }, { "const": "hailuo", "type": "string" }, { "const": "vidu", "type": "string" } ], "description": "Public scene-video option code." } }, "type": "object", "description": "Product-specific generation controls." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "lipSync": { "type": "boolean", "description": "Whether the MV should use the supported lip-sync workflow." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "prompt": { "maxLength": 3000, "type": "string", "description": "Primary creative or operation instruction." }, "referenceImages": { "items": { "minLength": 1, "type": "string" }, "maxItems": 7, "type": "array", "description": "Public reference image URLs." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "source": { "anyOf": [ { "additionalProperties": false, "properties": { "clipId": { "minLength": 1, "type": "string", "description": "Source clip identifier." }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "suno", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "clipId" ], "type": "object" }, { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "description": "Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.", "exclusiveMinimum": 0, "type": "number" }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object" } ], "description": "Public source media or product reference." }, "srtUrl": { "minLength": 1, "type": "string", "description": "Public URL of caller-supplied SRT subtitles." }, "subtitle": { "additionalProperties": false, "properties": { "fallback": { "anyOf": [ { "const": "fail", "type": "string" }, { "const": "continue_without_subtitles", "type": "string" } ], "description": "Behavior when the preferred subtitle path cannot complete." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." }, "mode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "provided", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Operation or product mode discriminator for this schema variant." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "premium", "type": "string" } ], "description": "Requested public quality tier." }, "required": { "type": "boolean", "description": "Whether the selected subtitle policy must succeed." } }, "type": "object", "description": "MV subtitle generation and fallback policy." }, "subtitleColor": { "maxLength": 20, "type": "string", "description": "Requested subtitle foreground color." }, "subtitles": { "type": "boolean", "description": "Whether subtitles are enabled for the MV." }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "mode", "source" ], "type": "object" } ] } }, "multipart/form-data": { "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "aspectRatio": { "anyOf": [ { "const": "16:9", "type": "string" }, { "const": "9:16", "type": "string" }, { "const": "1:1", "type": "string" }, { "const": "4:3", "type": "string" }, { "const": "3:4", "type": "string" } ], "description": "Requested output aspect ratio." }, "characterImage": { "minLength": 1, "type": "string", "description": "Public character reference image URL." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "generation": { "additionalProperties": false, "properties": { "creativeMode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "lyrics_story", "type": "string" }, { "const": "prompt_story", "type": "string" }, { "const": "mood_visual", "type": "string" }, { "const": "performance", "type": "string" } ], "description": "Creative intent used by Fast MV prompt and reference planning." }, "lipReferenceImages": { "description": "Ordered Premium V2 singer portrait URLs; the first item maps to the first singer.", "items": { "minLength": 1, "type": "string" }, "maxItems": 2, "minItems": 1, "type": "array" }, "managedVersion": { "anyOf": [ { "const": "oneclick-v1", "type": "string" }, { "const": "premium-v2", "type": "string" } ], "description": "Managed Fast MV engine version. Existing clients default to oneclick-v1; premium-v2 must be selected explicitly." }, "motionPreset": { "anyOf": [ { "const": "stable_performance", "type": "string" }, { "const": "cinematic_light", "type": "string" }, { "const": "dynamic_dance", "type": "string" }, { "const": "lip_sync_closeup", "type": "string" } ], "description": "Fast MV motion prompt policy." }, "performanceMode": { "anyOf": [ { "const": "sing", "type": "string" }, { "const": "sing_perform", "type": "string" }, { "const": "perform", "type": "string" }, { "const": "dance", "type": "string" } ], "description": "Premium V2 performance mode: singing, singing with performance, instrumental performance, or dance." }, "promptMode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "verbatim", "type": "string" }, { "const": "creative_brief", "type": "string" } ], "description": "Whether Fast MV preserves or compiles the caller prompt." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "high", "type": "string" } ], "description": "Requested public quality tier." }, "referenceStrategy": { "anyOf": [ { "const": "direct", "type": "string" }, { "const": "synthesize", "type": "string" } ], "description": "Fast MV policy for direct or synthesized references." }, "style": { "maxLength": 200, "type": "string", "description": "Requested creative style direction." }, "subtitleMode": { "anyOf": [ { "const": "vidu", "type": "string" }, { "const": "custom", "type": "string" } ], "description": "Fast MV subtitle rendering mode." }, "visualBoard": { "additionalProperties": false, "properties": { "imageProvider": { "anyOf": [ { "const": "gpt-image-2", "type": "string" }, { "const": "p-image", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public image-generation option code." }, "preset": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "speed", "type": "string" }, { "const": "detail", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Visual Board speed/detail policy." } }, "type": "object", "description": "Fast MV Visual Board configuration." } }, "type": "object", "description": "Product-specific generation controls." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "lipSync": { "type": "boolean", "description": "Whether the MV should use the supported lip-sync workflow." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "fast", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "prompt": { "maxLength": 3000, "type": "string", "description": "Primary creative or operation instruction." }, "referenceImages": { "items": { "minLength": 1, "type": "string" }, "maxItems": 7, "type": "array", "description": "Public reference image URLs." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "source": { "anyOf": [ { "additionalProperties": false, "properties": { "clipId": { "minLength": 1, "type": "string", "description": "Source clip identifier." }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "suno", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "clipId" ], "type": "object" }, { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "description": "Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.", "exclusiveMinimum": 0, "type": "number" }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object" } ], "description": "Public source media or product reference." }, "srtUrl": { "minLength": 1, "type": "string", "description": "Public URL of caller-supplied SRT subtitles." }, "subtitle": { "additionalProperties": false, "properties": { "fallback": { "anyOf": [ { "const": "fail", "type": "string" }, { "const": "continue_without_subtitles", "type": "string" } ], "description": "Behavior when the preferred subtitle path cannot complete." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." }, "mode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "provided", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Operation or product mode discriminator for this schema variant." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "premium", "type": "string" } ], "description": "Requested public quality tier." }, "required": { "type": "boolean", "description": "Whether the selected subtitle policy must succeed." } }, "type": "object", "description": "MV subtitle generation and fallback policy." }, "subtitleColor": { "maxLength": 20, "type": "string", "description": "Requested subtitle foreground color." }, "subtitles": { "type": "boolean", "description": "Whether subtitles are enabled for the MV." }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "mode", "source" ], "type": "object" }, { "additionalProperties": false, "properties": { "aspectRatio": { "anyOf": [ { "const": "16:9", "type": "string" }, { "const": "9:16", "type": "string" }, { "const": "1:1", "type": "string" }, { "const": "4:3", "type": "string" }, { "const": "3:4", "type": "string" } ], "description": "Requested output aspect ratio." }, "characterImage": { "minLength": 1, "type": "string", "description": "Public character reference image URL." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "generation": { "additionalProperties": false, "properties": { "imageProvider": { "anyOf": [ { "const": "p-image", "type": "string" }, { "const": "gpt-image-2", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public image-generation option code." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoProvider": { "anyOf": [ { "const": "p-video", "type": "string" }, { "const": "hailuo", "type": "string" }, { "const": "vidu", "type": "string" } ], "description": "Public scene-video option code." } }, "type": "object", "description": "Product-specific generation controls." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "lipSync": { "type": "boolean", "description": "Whether the MV should use the supported lip-sync workflow." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "prompt": { "maxLength": 3000, "type": "string", "description": "Primary creative or operation instruction." }, "referenceImages": { "items": { "minLength": 1, "type": "string" }, "maxItems": 7, "type": "array", "description": "Public reference image URLs." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "source": { "anyOf": [ { "additionalProperties": false, "properties": { "clipId": { "minLength": 1, "type": "string", "description": "Source clip identifier." }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "suno", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "clipId" ], "type": "object" }, { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "description": "Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.", "exclusiveMinimum": 0, "type": "number" }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object" } ], "description": "Public source media or product reference." }, "srtUrl": { "minLength": 1, "type": "string", "description": "Public URL of caller-supplied SRT subtitles." }, "subtitle": { "additionalProperties": false, "properties": { "fallback": { "anyOf": [ { "const": "fail", "type": "string" }, { "const": "continue_without_subtitles", "type": "string" } ], "description": "Behavior when the preferred subtitle path cannot complete." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." }, "mode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "provided", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Operation or product mode discriminator for this schema variant." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "premium", "type": "string" } ], "description": "Requested public quality tier." }, "required": { "type": "boolean", "description": "Whether the selected subtitle policy must succeed." } }, "type": "object", "description": "MV subtitle generation and fallback policy." }, "subtitleColor": { "maxLength": 20, "type": "string", "description": "Requested subtitle foreground color." }, "subtitles": { "type": "boolean", "description": "Whether subtitles are enabled for the MV." }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "mode", "source" ], "type": "object" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "checks": { "additionalProperties": false, "properties": { "characterImage": { "properties": { "clipId": { "type": "string" }, "durationSec": { "type": "number" }, "kind": { "type": "string" }, "processingMode": { "type": "string" }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number" }, "startSec": { "minimum": 0, "type": "number" } }, "type": "object" }, "sourceDurationSec": { "type": "number" }, "status": { "const": "ok", "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "kind" ], "type": "object" }, "referenceImages": { "items": { "properties": { "clipId": { "type": "string" }, "durationSec": { "type": "number" }, "kind": { "type": "string" }, "processingMode": { "type": "string" }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number" }, "startSec": { "minimum": 0, "type": "number" } }, "type": "object" }, "sourceDurationSec": { "type": "number" }, "status": { "const": "ok", "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "kind" ], "type": "object" }, "type": "array" }, "source": { "properties": { "clipId": { "type": "string" }, "durationSec": { "type": "number" }, "kind": { "type": "string" }, "processingMode": { "type": "string" }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number" }, "startSec": { "minimum": 0, "type": "number" } }, "type": "object" }, "sourceDurationSec": { "type": "number" }, "status": { "const": "ok", "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "kind" ], "type": "object" }, "srtUrl": { "properties": { "clipId": { "type": "string" }, "durationSec": { "type": "number" }, "kind": { "type": "string" }, "processingMode": { "type": "string" }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number" }, "startSec": { "minimum": 0, "type": "number" } }, "type": "object" }, "sourceDurationSec": { "type": "number" }, "status": { "const": "ok", "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "kind" ], "type": "object" }, "visualBoard": { "properties": { "clipId": { "type": "string" }, "durationSec": { "type": "number" }, "kind": { "type": "string" }, "processingMode": { "type": "string" }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number" }, "startSec": { "minimum": 0, "type": "number" } }, "type": "object" }, "sourceDurationSec": { "type": "number" }, "status": { "const": "ok", "type": "string" }, "url": { "type": "string" } }, "required": [ "status", "kind" ], "type": "object" } }, "required": [ "source", "referenceImages" ], "type": "object" }, "creditsRequired": { "minimum": 0, "type": "number" }, "expiresAt": { "type": "string" }, "mode": { "enum": [ "fast", "studio" ], "type": "string" }, "preflightId": { "type": "string" }, "quote": { "additionalProperties": false, "properties": { "assumptions": { "items": { "type": "string" }, "type": "array" }, "baseCredits": { "type": "number" }, "billingIncrementCredits": { "minimum": 0.0001, "type": "number" }, "breakdown": { "additionalProperties": false, "properties": { "base": { "type": "number" }, "composeOperations": { "type": "number" }, "duration": { "type": "number" }, "estimatedSceneCount": { "type": "number" }, "finalize": { "type": "number" }, "lipSync": { "type": "number" }, "renderPerScene": { "type": "number" }, "scenes": { "type": "number" }, "visualBoard": { "type": "number" } }, "type": "object" }, "calculatedSubtotalCredits": { "type": "number" }, "credits": { "minimum": 0, "type": "number" }, "discountCredits": { "type": "number" }, "expiresAt": { "type": "string" }, "operation": { "type": "string" }, "pricingVersion": { "type": "number" }, "quoteId": { "type": "string" }, "settlementPolicyVersion": { "type": "string" }, "settlementRoundingCredits": { "type": "number" }, "warningCodes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "credits", "breakdown" ], "type": "object" }, "quoteType": { "const": "validated_estimate", "type": "string" }, "warningCodes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "preflightId", "expiresAt", "quoteType", "mode", "creditsRequired", "warningCodes", "checks", "quote" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "408": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 408" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 409" }, "413": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 413" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 502" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Preflight MV create", "tags": [ "MV" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/mv/quote": { "post": { "description": "Customer-facing pricing preview for Fast and Studio MV generation and paid follow-up operations. The response includes a short-lived quoteId that can be supplied with the operation; execution reprices and rejects before direct debit if the current price exceeds the quoted/maxCredits ceiling. Create quotes are lightweight and do not validate remote media resources.", "operationId": "postApiV1MvQuote", "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "durationSec": { "maximum": 600, "minimum": 10, "type": "number", "description": "Requested or known media duration in seconds." }, "lipSync": { "type": "boolean", "description": "Whether the MV should use the supported lip-sync workflow." }, "managedVersion": { "anyOf": [ { "const": "oneclick-v1", "type": "string" }, { "const": "premium-v2", "type": "string" } ], "description": "Managed Fast MV engine version. Existing clients default to oneclick-v1; premium-v2 must be selected explicitly." }, "mode": { "const": "fast", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "performanceMode": { "anyOf": [ { "const": "sing", "type": "string" }, { "const": "sing_perform", "type": "string" }, { "const": "perform", "type": "string" }, { "const": "dance", "type": "string" } ], "description": "Premium V2 performance mode: singing, singing with performance, instrumental performance, or dance." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "high", "type": "string" } ], "description": "Requested public quality tier." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "step": { "const": "create", "type": "string", "description": "Quoted operation step discriminator." }, "subtitleMode": { "anyOf": [ { "const": "vidu", "type": "string" }, { "const": "custom", "type": "string" } ], "description": "Fast MV subtitle rendering mode." }, "visualBoardImageCount": { "maximum": 50, "minimum": 1, "type": "number", "description": "Number of generated Visual Board images to price." }, "visualBoardImageProvider": { "anyOf": [ { "const": "gpt-image-2", "type": "string" }, { "const": "p-image", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public Visual Board image option code." }, "visualBoardReferenceImageCount": { "maximum": 16, "minimum": 0, "type": "number", "description": "Number of billed Visual Board reference images." }, "visualBoardStrategy": { "const": "direct_scene_images", "type": "string", "description": "Public Visual Board pricing strategy." } }, "required": [ "mode", "durationSec" ], "type": "object" }, { "additionalProperties": false, "properties": { "mode": { "const": "fast", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "mvId": { "minLength": 1, "type": "string", "description": "MV identifier targeted by this operation." }, "sceneIndex": { "minimum": 0, "type": "number", "description": "Zero-based scene index." }, "step": { "const": "scene-edit", "type": "string", "description": "Quoted operation step discriminator." } }, "required": [ "mode", "step", "mvId", "sceneIndex" ], "type": "object" }, { "additionalProperties": false, "properties": { "mode": { "const": "fast", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "mvId": { "minLength": 1, "type": "string", "description": "MV identifier targeted by this operation." }, "step": { "const": "compose", "type": "string", "description": "Quoted operation step discriminator." } }, "required": [ "mode", "step", "mvId" ], "type": "object" }, { "additionalProperties": false, "properties": { "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "step": { "const": "storyboard", "type": "string", "description": "Quoted operation step discriminator." }, "visualBoardImageCount": { "maximum": 50, "minimum": 1, "type": "number", "description": "Number of generated Visual Board images to price." }, "visualBoardImageProvider": { "anyOf": [ { "const": "gpt-image-2", "type": "string" }, { "const": "p-image", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public Visual Board image option code." }, "visualBoardReferenceImageCount": { "maximum": 16, "minimum": 0, "type": "number", "description": "Number of billed Visual Board reference images." }, "visualBoardStrategy": { "const": "direct_scene_images", "type": "string", "description": "Public Visual Board pricing strategy." } }, "required": [ "mode", "step" ], "type": "object" }, { "additionalProperties": false, "properties": { "draft": { "type": "boolean", "description": "Whether to use the supported draft rendering policy." }, "durationSec": { "maximum": 16, "minimum": 1, "type": "number", "description": "Requested or known media duration in seconds." }, "fps": { "anyOf": [ { "const": 24, "type": "number" }, { "const": 48, "type": "number" } ], "description": "Requested numeric output frame rate." }, "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "step": { "const": "render-scene", "type": "string", "description": "Quoted operation step discriminator." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoProvider": { "anyOf": [ { "const": "p-video", "type": "string" }, { "const": "hailuo", "type": "string" }, { "const": "vidu", "type": "string" } ], "description": "Public scene-video option code." } }, "required": [ "mode", "step", "videoProvider", "resolution", "durationSec" ], "type": "object" }, { "additionalProperties": false, "properties": { "draft": { "type": "boolean", "description": "Whether to use the supported draft rendering policy." }, "fps": { "anyOf": [ { "const": 24, "type": "number" }, { "const": 48, "type": "number" } ], "description": "Requested numeric output frame rate." }, "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "mvId": { "minLength": 1, "type": "string", "description": "MV identifier targeted by this operation." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "sceneIndexes": { "items": { "minimum": 0, "type": "number" }, "maxItems": 30, "minItems": 1, "type": "array", "uniqueItems": true, "description": "Unique zero-based scene indexes included in the operation." }, "step": { "const": "render-batch", "type": "string", "description": "Quoted operation step discriminator." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoProvider": { "anyOf": [ { "const": "p-video", "type": "string" }, { "const": "hailuo", "type": "string" }, { "const": "vidu", "type": "string" } ], "description": "Public scene-video option code." } }, "required": [ "mode", "step", "mvId", "sceneIndexes", "videoProvider", "resolution" ], "type": "object" }, { "additionalProperties": false, "properties": { "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "mvId": { "minLength": 1, "type": "string", "description": "MV identifier targeted by this operation." }, "sceneIndex": { "minimum": 0, "type": "number", "description": "Zero-based scene index." }, "step": { "const": "regenerate-image", "type": "string", "description": "Quoted operation step discriminator." } }, "required": [ "mode", "step", "mvId", "sceneIndex" ], "type": "object" }, { "additionalProperties": false, "properties": { "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "mvId": { "minLength": 1, "type": "string", "description": "MV identifier targeted by this operation." }, "step": { "const": "finalize", "type": "string", "description": "Quoted operation step discriminator." } }, "required": [ "mode", "step", "mvId" ], "type": "object" }, { "additionalProperties": false, "properties": { "draft": { "type": "boolean", "description": "Whether to use the supported draft rendering policy." }, "estimatedSceneCount": { "maximum": 30, "minimum": 1, "type": "number", "description": "Estimated number of Studio scenes for total pricing." }, "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "perSceneDurationSec": { "maximum": 16, "minimum": 1, "type": "number", "description": "Estimated duration of each Studio scene in seconds." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "step": { "const": "total", "type": "string", "description": "Quoted operation step discriminator." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoProvider": { "anyOf": [ { "const": "p-video", "type": "string" }, { "const": "hailuo", "type": "string" }, { "const": "vidu", "type": "string" } ], "description": "Public scene-video option code." }, "visualBoardImageCount": { "maximum": 50, "minimum": 1, "type": "number", "description": "Number of generated Visual Board images to price." }, "visualBoardImageProvider": { "anyOf": [ { "const": "gpt-image-2", "type": "string" }, { "const": "p-image", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public Visual Board image option code." }, "visualBoardStrategy": { "const": "direct_scene_images", "type": "string", "description": "Public Visual Board pricing strategy." } }, "required": [ "mode", "step", "videoProvider", "resolution", "perSceneDurationSec", "estimatedSceneCount" ], "type": "object" } ] } }, "application/x-www-form-urlencoded": { "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "durationSec": { "maximum": 600, "minimum": 10, "type": "number", "description": "Requested or known media duration in seconds." }, "lipSync": { "type": "boolean", "description": "Whether the MV should use the supported lip-sync workflow." }, "managedVersion": { "anyOf": [ { "const": "oneclick-v1", "type": "string" }, { "const": "premium-v2", "type": "string" } ], "description": "Managed Fast MV engine version. Existing clients default to oneclick-v1; premium-v2 must be selected explicitly." }, "mode": { "const": "fast", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "performanceMode": { "anyOf": [ { "const": "sing", "type": "string" }, { "const": "sing_perform", "type": "string" }, { "const": "perform", "type": "string" }, { "const": "dance", "type": "string" } ], "description": "Premium V2 performance mode: singing, singing with performance, instrumental performance, or dance." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "high", "type": "string" } ], "description": "Requested public quality tier." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "step": { "const": "create", "type": "string", "description": "Quoted operation step discriminator." }, "subtitleMode": { "anyOf": [ { "const": "vidu", "type": "string" }, { "const": "custom", "type": "string" } ], "description": "Fast MV subtitle rendering mode." }, "visualBoardImageCount": { "maximum": 50, "minimum": 1, "type": "number", "description": "Number of generated Visual Board images to price." }, "visualBoardImageProvider": { "anyOf": [ { "const": "gpt-image-2", "type": "string" }, { "const": "p-image", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public Visual Board image option code." }, "visualBoardReferenceImageCount": { "maximum": 16, "minimum": 0, "type": "number", "description": "Number of billed Visual Board reference images." }, "visualBoardStrategy": { "const": "direct_scene_images", "type": "string", "description": "Public Visual Board pricing strategy." } }, "required": [ "mode", "durationSec" ], "type": "object" }, { "additionalProperties": false, "properties": { "mode": { "const": "fast", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "mvId": { "minLength": 1, "type": "string", "description": "MV identifier targeted by this operation." }, "sceneIndex": { "minimum": 0, "type": "number", "description": "Zero-based scene index." }, "step": { "const": "scene-edit", "type": "string", "description": "Quoted operation step discriminator." } }, "required": [ "mode", "step", "mvId", "sceneIndex" ], "type": "object" }, { "additionalProperties": false, "properties": { "mode": { "const": "fast", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "mvId": { "minLength": 1, "type": "string", "description": "MV identifier targeted by this operation." }, "step": { "const": "compose", "type": "string", "description": "Quoted operation step discriminator." } }, "required": [ "mode", "step", "mvId" ], "type": "object" }, { "additionalProperties": false, "properties": { "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "step": { "const": "storyboard", "type": "string", "description": "Quoted operation step discriminator." }, "visualBoardImageCount": { "maximum": 50, "minimum": 1, "type": "number", "description": "Number of generated Visual Board images to price." }, "visualBoardImageProvider": { "anyOf": [ { "const": "gpt-image-2", "type": "string" }, { "const": "p-image", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public Visual Board image option code." }, "visualBoardReferenceImageCount": { "maximum": 16, "minimum": 0, "type": "number", "description": "Number of billed Visual Board reference images." }, "visualBoardStrategy": { "const": "direct_scene_images", "type": "string", "description": "Public Visual Board pricing strategy." } }, "required": [ "mode", "step" ], "type": "object" }, { "additionalProperties": false, "properties": { "draft": { "type": "boolean", "description": "Whether to use the supported draft rendering policy." }, "durationSec": { "maximum": 16, "minimum": 1, "type": "number", "description": "Requested or known media duration in seconds." }, "fps": { "anyOf": [ { "const": 24, "type": "number" }, { "const": 48, "type": "number" } ], "description": "Requested numeric output frame rate." }, "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "step": { "const": "render-scene", "type": "string", "description": "Quoted operation step discriminator." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoProvider": { "anyOf": [ { "const": "p-video", "type": "string" }, { "const": "hailuo", "type": "string" }, { "const": "vidu", "type": "string" } ], "description": "Public scene-video option code." } }, "required": [ "mode", "step", "videoProvider", "resolution", "durationSec" ], "type": "object" }, { "additionalProperties": false, "properties": { "draft": { "type": "boolean", "description": "Whether to use the supported draft rendering policy." }, "fps": { "anyOf": [ { "const": 24, "type": "number" }, { "const": 48, "type": "number" } ], "description": "Requested numeric output frame rate." }, "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "mvId": { "minLength": 1, "type": "string", "description": "MV identifier targeted by this operation." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "sceneIndexes": { "items": { "minimum": 0, "type": "number" }, "maxItems": 30, "minItems": 1, "type": "array", "uniqueItems": true, "description": "Unique zero-based scene indexes included in the operation." }, "step": { "const": "render-batch", "type": "string", "description": "Quoted operation step discriminator." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoProvider": { "anyOf": [ { "const": "p-video", "type": "string" }, { "const": "hailuo", "type": "string" }, { "const": "vidu", "type": "string" } ], "description": "Public scene-video option code." } }, "required": [ "mode", "step", "mvId", "sceneIndexes", "videoProvider", "resolution" ], "type": "object" }, { "additionalProperties": false, "properties": { "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "mvId": { "minLength": 1, "type": "string", "description": "MV identifier targeted by this operation." }, "sceneIndex": { "minimum": 0, "type": "number", "description": "Zero-based scene index." }, "step": { "const": "regenerate-image", "type": "string", "description": "Quoted operation step discriminator." } }, "required": [ "mode", "step", "mvId", "sceneIndex" ], "type": "object" }, { "additionalProperties": false, "properties": { "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "mvId": { "minLength": 1, "type": "string", "description": "MV identifier targeted by this operation." }, "step": { "const": "finalize", "type": "string", "description": "Quoted operation step discriminator." } }, "required": [ "mode", "step", "mvId" ], "type": "object" }, { "additionalProperties": false, "properties": { "draft": { "type": "boolean", "description": "Whether to use the supported draft rendering policy." }, "estimatedSceneCount": { "maximum": 30, "minimum": 1, "type": "number", "description": "Estimated number of Studio scenes for total pricing." }, "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "perSceneDurationSec": { "maximum": 16, "minimum": 1, "type": "number", "description": "Estimated duration of each Studio scene in seconds." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "step": { "const": "total", "type": "string", "description": "Quoted operation step discriminator." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoProvider": { "anyOf": [ { "const": "p-video", "type": "string" }, { "const": "hailuo", "type": "string" }, { "const": "vidu", "type": "string" } ], "description": "Public scene-video option code." }, "visualBoardImageCount": { "maximum": 50, "minimum": 1, "type": "number", "description": "Number of generated Visual Board images to price." }, "visualBoardImageProvider": { "anyOf": [ { "const": "gpt-image-2", "type": "string" }, { "const": "p-image", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public Visual Board image option code." }, "visualBoardStrategy": { "const": "direct_scene_images", "type": "string", "description": "Public Visual Board pricing strategy." } }, "required": [ "mode", "step", "videoProvider", "resolution", "perSceneDurationSec", "estimatedSceneCount" ], "type": "object" } ] } }, "multipart/form-data": { "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "durationSec": { "maximum": 600, "minimum": 10, "type": "number", "description": "Requested or known media duration in seconds." }, "lipSync": { "type": "boolean", "description": "Whether the MV should use the supported lip-sync workflow." }, "managedVersion": { "anyOf": [ { "const": "oneclick-v1", "type": "string" }, { "const": "premium-v2", "type": "string" } ], "description": "Managed Fast MV engine version. Existing clients default to oneclick-v1; premium-v2 must be selected explicitly." }, "mode": { "const": "fast", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "performanceMode": { "anyOf": [ { "const": "sing", "type": "string" }, { "const": "sing_perform", "type": "string" }, { "const": "perform", "type": "string" }, { "const": "dance", "type": "string" } ], "description": "Premium V2 performance mode: singing, singing with performance, instrumental performance, or dance." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "high", "type": "string" } ], "description": "Requested public quality tier." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "step": { "const": "create", "type": "string", "description": "Quoted operation step discriminator." }, "subtitleMode": { "anyOf": [ { "const": "vidu", "type": "string" }, { "const": "custom", "type": "string" } ], "description": "Fast MV subtitle rendering mode." }, "visualBoardImageCount": { "maximum": 50, "minimum": 1, "type": "number", "description": "Number of generated Visual Board images to price." }, "visualBoardImageProvider": { "anyOf": [ { "const": "gpt-image-2", "type": "string" }, { "const": "p-image", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public Visual Board image option code." }, "visualBoardReferenceImageCount": { "maximum": 16, "minimum": 0, "type": "number", "description": "Number of billed Visual Board reference images." }, "visualBoardStrategy": { "const": "direct_scene_images", "type": "string", "description": "Public Visual Board pricing strategy." } }, "required": [ "mode", "durationSec" ], "type": "object" }, { "additionalProperties": false, "properties": { "mode": { "const": "fast", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "mvId": { "minLength": 1, "type": "string", "description": "MV identifier targeted by this operation." }, "sceneIndex": { "minimum": 0, "type": "number", "description": "Zero-based scene index." }, "step": { "const": "scene-edit", "type": "string", "description": "Quoted operation step discriminator." } }, "required": [ "mode", "step", "mvId", "sceneIndex" ], "type": "object" }, { "additionalProperties": false, "properties": { "mode": { "const": "fast", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "mvId": { "minLength": 1, "type": "string", "description": "MV identifier targeted by this operation." }, "step": { "const": "compose", "type": "string", "description": "Quoted operation step discriminator." } }, "required": [ "mode", "step", "mvId" ], "type": "object" }, { "additionalProperties": false, "properties": { "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "step": { "const": "storyboard", "type": "string", "description": "Quoted operation step discriminator." }, "visualBoardImageCount": { "maximum": 50, "minimum": 1, "type": "number", "description": "Number of generated Visual Board images to price." }, "visualBoardImageProvider": { "anyOf": [ { "const": "gpt-image-2", "type": "string" }, { "const": "p-image", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public Visual Board image option code." }, "visualBoardReferenceImageCount": { "maximum": 16, "minimum": 0, "type": "number", "description": "Number of billed Visual Board reference images." }, "visualBoardStrategy": { "const": "direct_scene_images", "type": "string", "description": "Public Visual Board pricing strategy." } }, "required": [ "mode", "step" ], "type": "object" }, { "additionalProperties": false, "properties": { "draft": { "type": "boolean", "description": "Whether to use the supported draft rendering policy." }, "durationSec": { "maximum": 16, "minimum": 1, "type": "number", "description": "Requested or known media duration in seconds." }, "fps": { "anyOf": [ { "const": 24, "type": "number" }, { "const": 48, "type": "number" } ], "description": "Requested numeric output frame rate." }, "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "step": { "const": "render-scene", "type": "string", "description": "Quoted operation step discriminator." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoProvider": { "anyOf": [ { "const": "p-video", "type": "string" }, { "const": "hailuo", "type": "string" }, { "const": "vidu", "type": "string" } ], "description": "Public scene-video option code." } }, "required": [ "mode", "step", "videoProvider", "resolution", "durationSec" ], "type": "object" }, { "additionalProperties": false, "properties": { "draft": { "type": "boolean", "description": "Whether to use the supported draft rendering policy." }, "fps": { "anyOf": [ { "const": 24, "type": "number" }, { "const": 48, "type": "number" } ], "description": "Requested numeric output frame rate." }, "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "mvId": { "minLength": 1, "type": "string", "description": "MV identifier targeted by this operation." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "sceneIndexes": { "items": { "minimum": 0, "type": "number" }, "maxItems": 30, "minItems": 1, "type": "array", "uniqueItems": true, "description": "Unique zero-based scene indexes included in the operation." }, "step": { "const": "render-batch", "type": "string", "description": "Quoted operation step discriminator." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoProvider": { "anyOf": [ { "const": "p-video", "type": "string" }, { "const": "hailuo", "type": "string" }, { "const": "vidu", "type": "string" } ], "description": "Public scene-video option code." } }, "required": [ "mode", "step", "mvId", "sceneIndexes", "videoProvider", "resolution" ], "type": "object" }, { "additionalProperties": false, "properties": { "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "mvId": { "minLength": 1, "type": "string", "description": "MV identifier targeted by this operation." }, "sceneIndex": { "minimum": 0, "type": "number", "description": "Zero-based scene index." }, "step": { "const": "regenerate-image", "type": "string", "description": "Quoted operation step discriminator." } }, "required": [ "mode", "step", "mvId", "sceneIndex" ], "type": "object" }, { "additionalProperties": false, "properties": { "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "mvId": { "minLength": 1, "type": "string", "description": "MV identifier targeted by this operation." }, "step": { "const": "finalize", "type": "string", "description": "Quoted operation step discriminator." } }, "required": [ "mode", "step", "mvId" ], "type": "object" }, { "additionalProperties": false, "properties": { "draft": { "type": "boolean", "description": "Whether to use the supported draft rendering policy." }, "estimatedSceneCount": { "maximum": 30, "minimum": 1, "type": "number", "description": "Estimated number of Studio scenes for total pricing." }, "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "perSceneDurationSec": { "maximum": 16, "minimum": 1, "type": "number", "description": "Estimated duration of each Studio scene in seconds." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "step": { "const": "total", "type": "string", "description": "Quoted operation step discriminator." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoProvider": { "anyOf": [ { "const": "p-video", "type": "string" }, { "const": "hailuo", "type": "string" }, { "const": "vidu", "type": "string" } ], "description": "Public scene-video option code." }, "visualBoardImageCount": { "maximum": 50, "minimum": 1, "type": "number", "description": "Number of generated Visual Board images to price." }, "visualBoardImageProvider": { "anyOf": [ { "const": "gpt-image-2", "type": "string" }, { "const": "p-image", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public Visual Board image option code." }, "visualBoardStrategy": { "const": "direct_scene_images", "type": "string", "description": "Public Visual Board pricing strategy." } }, "required": [ "mode", "step", "videoProvider", "resolution", "perSceneDurationSec", "estimatedSceneCount" ], "type": "object" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "assumptions": { "items": { "type": "string" }, "type": "array" }, "baseCredits": { "type": "number" }, "billingIncrementCredits": { "minimum": 0.0001, "type": "number" }, "breakdown": { "additionalProperties": false, "properties": { "base": { "type": "number" }, "composeOperations": { "type": "number" }, "duration": { "type": "number" }, "estimatedSceneCount": { "type": "number" }, "finalize": { "type": "number" }, "lipSync": { "type": "number" }, "renderPerScene": { "type": "number" }, "scenes": { "type": "number" }, "visualBoard": { "type": "number" } }, "type": "object" }, "calculatedSubtotalCredits": { "type": "number" }, "credits": { "minimum": 0, "type": "number" }, "discountCredits": { "type": "number" }, "expiresAt": { "type": "string" }, "operation": { "type": "string" }, "pricingVersion": { "type": "number" }, "quoteId": { "type": "string" }, "settlementPolicyVersion": { "type": "string" }, "settlementRoundingCredits": { "type": "number" }, "warningCodes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "credits", "breakdown" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Forbidden: the API key lacks the required scope or its IP policy rejects this request." }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "Quote MV credits", "tags": [ "MV" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/mv/{mvId}": { "delete": { "description": "Idempotently marks an MV deleted, removes it from list/read results, blocks new operations, and deletes known source, scene, rendering, and final assets with bounded concurrency. Task, operation, pricing, and billing records required for financial reconciliation remain subject to the platform audit-retention policy.", "operationId": "deleteApiV1MvById", "parameters": [ { "in": "path", "name": "mvId", "required": true, "schema": { "type": "string" }, "description": "MV identifier returned by create or read operations." } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "assetsDeleted": { "type": "number" }, "assetsFailed": { "type": "number" }, "id": { "type": "string" }, "status": { "const": "DELETED", "type": "string" } }, "required": [ "id", "status", "assetsDeleted", "assetsFailed" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "408": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 408" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 409" }, "413": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 413" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 502" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Delete MV", "tags": [ "MV" ], "security": [ { "ApiKeyAuth": [] } ] }, "get": { "description": "Returns the public MVView shape for Fast or Studio: source, prompt, scene timing, generated assets, finalMv, version, and capability flags. Some asset URLs may be short-lived; refresh by reading the MV again. Existing clients may omit historyLimit to retain the original complete renderingHistory response; new interactive clients can request 1-50 recent entries per scene. Selected entries and the latest playable Fast fallback are additionally retained when they fall outside that recent window.", "operationId": "getApiV1MvById", "parameters": [ { "in": "path", "name": "mvId", "required": true, "schema": { "type": "string" }, "description": "MV identifier returned by create or read operations." }, { "in": "query", "name": "historyLimit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Recent rendering-history entries retained per scene. Omit for the complete history." } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "billing": { "anyOf": [ { "properties": { "creditsCharged": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "creditsReserved": { "type": "number" }, "refundReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "refundedCredits": { "type": "number" }, "settlementStatus": { "anyOf": [ { "const": "PENDING", "type": "string" }, { "const": "CHARGED", "type": "string" }, { "const": "REFUNDED", "type": "string" } ] } }, "required": [ "creditsReserved", "creditsCharged", "refundedCredits", "settlementStatus", "refundReason" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "capabilities": { "properties": { "canEditManagedScene": { "type": "boolean" }, "canEditSceneFraming": { "type": "boolean" }, "canEditSceneImage": { "type": "boolean" }, "canEditScenePrompt": { "type": "boolean" }, "canFinalize": { "type": "boolean" }, "canLockCharacter": { "type": "boolean" }, "canPatchStageOutput": { "type": "boolean" }, "canRecompose": { "type": "boolean" }, "canRefreshFinalUrl": { "type": "boolean" }, "canRegenerateSceneImage": { "type": "boolean" }, "canRenderScene": { "type": "boolean" }, "canRerenderSceneWithImages": { "type": "boolean" }, "canRerenderSceneWithPrompt": { "type": "boolean" }, "canRetryFinalize": { "type": "boolean" }, "canSelectRendering": { "type": "boolean" }, "canTriggerRender": { "type": "boolean" }, "canUseCurrentFinal": { "type": "boolean" }, "finalizeAction": { "anyOf": [ { "anyOf": [ { "const": "finalize", "type": "string" }, { "const": "recompose", "type": "string" }, { "const": "retry_finalize", "type": "string" } ] }, { "type": "null" } ], "nullable": true }, "requiresFinalize": { "type": "boolean" } }, "required": [ "canEditScenePrompt", "canEditSceneImage", "canEditSceneFraming", "canRenderScene", "canSelectRendering", "canRegenerateSceneImage", "canTriggerRender", "canFinalize", "canLockCharacter", "canRefreshFinalUrl", "canRetryFinalize", "canRecompose", "canEditManagedScene", "canRerenderSceneWithPrompt", "canRerenderSceneWithImages", "requiresFinalize", "canUseCurrentFinal", "canPatchStageOutput" ], "type": "object" }, "characterAnchor": { "anyOf": [ { "properties": { "url": { "type": "string" } }, "required": [ "url" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "costSummary": { "properties": { "authorizedCredits": { "type": "number" }, "chargedCredits": { "type": "number" }, "netSpentCredits": { "type": "number" }, "operationCount": { "type": "number" }, "refundedCredits": { "type": "number" } }, "required": [ "authorizedCredits", "chargedCredits", "refundedCredits", "netSpentCredits", "operationCount" ], "type": "object" }, "createdAt": { "type": "string" }, "customerAction": { "anyOf": [ { "anyOf": [ { "const": "retry", "type": "string" }, { "const": "fix_input", "type": "string" }, { "const": "contact_support", "type": "string" }, { "const": "wait", "type": "string" } ] }, { "type": "null" } ], "nullable": true }, "deliveryStatus": { "enum": [ "drafting", "incomplete", "rendering", "packaging", "ready", "failed" ], "type": "string" }, "failedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "failureCategory": { "anyOf": [ { "anyOf": [ { "const": "customer_input", "type": "string" }, { "const": "provider_unavailable", "type": "string" }, { "const": "provider_failed", "type": "string" }, { "const": "provider_timeout", "type": "string" }, { "const": "platform_storage_failed", "type": "string" }, { "const": "subtitle_failed", "type": "string" }, { "const": "finalization_failed", "type": "string" }, { "const": "unknown", "type": "string" } ] }, { "type": "null" } ], "nullable": true }, "failureReason": { "anyOf": [ { "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true } }, "required": [ "code", "message" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "finalMv": { "anyOf": [ { "properties": { "assetId": { "type": "string" }, "assetStatus": { "anyOf": [ { "const": "READY", "type": "string" }, { "const": "EXPIRED", "type": "string" }, { "const": "DELETING", "type": "string" }, { "const": "DELETED", "type": "string" } ] }, "durationSec": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "expiresAt": { "type": "string" }, "finalizationRequired": { "type": "boolean" }, "finalizedVersion": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "id": { "type": "string" }, "isCurrent": { "type": "boolean" }, "resolution": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "retainedUntil": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "sourceVersion": { "type": "number" }, "staleReason": { "anyOf": [ { "anyOf": [ { "const": "missing_final", "type": "string" }, { "const": "final_processing", "type": "string" }, { "const": "final_expired", "type": "string" }, { "const": "source_rendering", "type": "string" }, { "const": "source_failed", "type": "string" }, { "const": "source_changed", "type": "string" }, { "const": "composition_unknown", "type": "string" }, { "const": "url_unavailable", "type": "string" } ] }, { "type": "null" } ], "nullable": true }, "status": { "anyOf": [ { "const": "PROCESSING", "type": "string" }, { "const": "READY", "type": "string" }, { "const": "EXPIRED", "type": "string" } ] }, "urlExpiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "videoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true } }, "required": [ "id", "status", "videoUrl", "durationSec", "resolution", "expiresAt", "isCurrent", "sourceVersion", "finalizedVersion", "finalizationRequired", "staleReason" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "finalUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "finalizationRequired": { "type": "boolean" }, "finalizedVersion": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "generation": { "properties": { "aspectRatio": { "type": "string" }, "draft": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "nullable": true }, "language": { "type": "string" }, "lipSync": { "type": "boolean" }, "managedVersion": { "anyOf": [ { "anyOf": [ { "const": "oneclick-v1", "type": "string" }, { "const": "premium-v2", "type": "string" } ], "description": "Managed Fast MV engine version. Existing clients default to oneclick-v1; premium-v2 must be selected explicitly." }, { "type": "null" } ], "nullable": true }, "performanceMode": { "anyOf": [ { "anyOf": [ { "const": "sing", "type": "string" }, { "const": "sing_perform", "type": "string" }, { "const": "perform", "type": "string" }, { "const": "dance", "type": "string" } ], "description": "Premium V2 performance mode: singing, singing with performance, instrumental performance, or dance." }, { "type": "null" } ], "nullable": true }, "resolution": { "type": "string" }, "subtitleColor": { "type": "string" }, "subtitles": { "type": "boolean" }, "videoProvider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true } }, "required": [ "aspectRatio", "resolution", "lipSync", "subtitles", "subtitleColor", "language", "draft", "videoProvider" ], "type": "object" }, "generationTaskId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "lastErrorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "lastErrorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "mode": { "enum": [ "fast", "studio" ], "type": "string" }, "mvId": { "type": "string" }, "progress": { "maximum": 100, "minimum": 0, "type": "number" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "referenceImages": { "items": { "properties": { "source": { "enum": [ "user", "auto_visual_board" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "url", "source" ], "type": "object" }, "type": "array" }, "refundable": { "type": "boolean" }, "retryable": { "type": "boolean" }, "scenes": { "items": { "properties": { "endSec": { "type": "number" }, "framing": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "imageAssetId": { "type": "string" }, "imagePrompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "imageRetainedUntil": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "imageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "imageUrlExpiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "index": { "type": "number" }, "lyricsWindow": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "prompt": { "type": "string" }, "renderingHistory": { "items": { "properties": { "assetId": { "type": "string" }, "assetStatus": { "enum": [ "READY", "EXPIRED", "DELETING", "DELETED" ], "type": "string" }, "createdAt": { "type": "string" }, "durationSec": { "type": "number" }, "id": { "type": "string" }, "isSelectable": { "type": "boolean" }, "isSelected": { "type": "boolean" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "referenceImages": { "items": { "type": "string" }, "type": "array" }, "retainedUntil": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "urlExpiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "videoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true } }, "required": [ "id", "videoUrl", "durationSec", "isSelected", "isSelectable", "createdAt" ], "type": "object" }, "type": "array" }, "sourceJob": { "anyOf": [ { "properties": { "createdAt": { "type": "string" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "id": { "type": "string" }, "isComposable": { "type": "boolean" }, "status": { "anyOf": [ { "const": "PLANNED", "type": "string" }, { "const": "IMAGE_READY", "type": "string" }, { "const": "RENDERING", "type": "string" }, { "const": "READY", "type": "string" }, { "const": "FAILED", "type": "string" }, { "const": "STALE", "type": "string" } ] } }, "required": [ "id", "status", "isComposable", "errorCode", "errorMessage", "createdAt" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "startSec": { "type": "number" }, "status": { "enum": [ "PLANNED", "IMAGE_READY", "RENDERING", "READY", "FAILED", "STALE" ], "type": "string" }, "videoPrompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "videoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true } }, "required": [ "index", "startSec", "endSec", "lyricsWindow", "framing", "prompt", "imagePrompt", "videoPrompt", "imageUrl", "videoUrl", "status", "renderingHistory" ], "type": "object" }, "type": "array" }, "source": { "properties": { "audioUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "clipId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "durationSec": { "type": "number" }, "lyrics": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "range": { "anyOf": [ { "properties": { "endSec": { "minimum": 0, "type": "number" }, "startSec": { "minimum": 0, "type": "number" } }, "type": "object" }, { "type": "null" } ], "nullable": true }, "sourceDurationSec": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "type": { "enum": [ "suno", "audio" ], "type": "string" } }, "required": [ "type", "durationSec" ], "type": "object" }, "sourceVersion": { "type": "number" }, "stages": { "properties": { "creativeConcept": {}, "emotionMap": {}, "narrativeArc": {} }, "required": [ "emotionMap", "creativeConcept", "narrativeArc" ], "type": "object" }, "staleReason": { "anyOf": [ { "anyOf": [ { "const": "missing_final", "type": "string" }, { "const": "final_processing", "type": "string" }, { "const": "final_expired", "type": "string" }, { "const": "source_rendering", "type": "string" }, { "const": "source_failed", "type": "string" }, { "const": "source_changed", "type": "string" }, { "const": "composition_unknown", "type": "string" }, { "const": "url_unavailable", "type": "string" } ] }, { "type": "null" } ], "nullable": true }, "status": { "enum": [ "PENDING", "GENERATING", "ACTION_REQUIRED", "READY", "RENDERING", "FINALIZING", "COMPLETED", "EDITING", "FAILED", "ARCHIVED", "DELETED" ], "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "updatedAt": { "type": "string" }, "version": { "type": "number" }, "warningCodes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "mvId", "mode", "status", "version", "source", "prompt", "title", "generation", "characterAnchor", "referenceImages", "scenes", "finalMv", "finalUrl", "sourceVersion", "finalizedVersion", "finalizationRequired", "staleReason", "progress", "deliveryStatus", "failureReason", "failureCategory", "retryable", "refundable", "customerAction", "billing", "costSummary", "stages", "warningCodes", "lastErrorCode", "lastErrorMessage", "failedAt", "generationTaskId", "createdAt", "updatedAt", "capabilities" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "Get MV", "tags": [ "MV" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/mv/{mvId}/final": { "get": { "description": "Read or refresh the current final MP4 URL. Returns a fresh short-lived presigned URL (60 minutes by default) only when ready=true and the final asset matches the current source composition. Stale or missing finals return ready=false with sourceVersion/finalizedVersion/staleReason/actionHint diagnostics. The response includes `videoUrl`; fetch it directly. `id` identifies the final asset and differs from `mvId`.", "operationId": "getApiV1MvByIdFinal", "parameters": [ { "in": "path", "name": "mvId", "required": true, "schema": { "type": "string" }, "description": "MV identifier returned by create or read operations." } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "actionHint": { "anyOf": [ { "anyOf": [ { "const": "wait", "type": "string" }, { "const": "refresh_final_url", "type": "string" }, { "const": "retry_finalize", "type": "string" }, { "const": "recompose_after_edit", "type": "string" }, { "const": "check_source", "type": "string" }, { "const": "contact_support", "type": "string" } ] }, { "type": "null" } ], "nullable": true }, "expiresInSec": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "failureMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "finalizationRequired": { "type": "boolean" }, "finalizedVersion": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "isCurrent": { "type": "boolean" }, "pollAfterSec": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "ready": { "type": "boolean" }, "retainedUntil": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "retryable": { "type": "boolean" }, "sourceVersion": { "type": "number" }, "staleReason": { "anyOf": [ { "anyOf": [ { "const": "missing_final", "type": "string" }, { "const": "final_processing", "type": "string" }, { "const": "final_expired", "type": "string" }, { "const": "source_rendering", "type": "string" }, { "const": "source_failed", "type": "string" }, { "const": "source_changed", "type": "string" }, { "const": "composition_unknown", "type": "string" }, { "const": "url_unavailable", "type": "string" } ] }, { "type": "null" } ], "nullable": true }, "status": { "type": "string" }, "urlExpiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "videoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true } }, "required": [ "id", "ready", "status", "videoUrl", "expiresInSec", "urlExpiresAt", "retainedUntil", "isCurrent", "sourceVersion", "finalizedVersion", "finalizationRequired", "staleReason", "failureCode", "failureMessage", "retryable", "pollAfterSec", "actionHint" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 502" } }, "summary": "Get final MV download URL", "tags": [ "MV" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/mv/{mvId}/finalize": { "post": { "description": "Create or refresh the final MP4 asset. Fast create normally auto-finalizes; explicit Fast finalize is used to recover a missing/failed final or recompose after successful Fast scene edits. For Fast, expectedVersion is recommended; if omitted, OmnAPI uses the latest MV version available when the request is accepted. Studio finalize stitches selected scene renderings and requires MVView.version as expectedVersion.", "operationId": "postApiV1MvByIdFinalize", "parameters": [ { "in": "path", "name": "mvId", "required": true, "schema": { "type": "string" }, "description": "MV identifier returned by create or read operations." }, { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "expectedVersion": { "description": "Fast compatibility/concurrency guard: when omitted, OmnAPI uses the current MVView.version; explicit stale values are rejected with 409.", "minimum": 0, "type": "number" }, "maxCredits": { "minimum": 0, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "retry": { "type": "boolean", "description": "Whether to retry a supported failed operation." } }, "type": "object" }, { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "expectedVersion": { "description": "Studio optimistic-concurrency guard: the MVView.version this edit is based on; rejected with 409 if the stored version has advanced. Not a platform/task field.", "minimum": 0, "type": "number" }, "maxCredits": { "minimum": 0, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "retry": { "type": "boolean", "description": "Whether to retry a supported failed operation." }, "scenes": { "items": { "properties": { "renderingId": { "minLength": 1, "type": "string", "description": "Scene rendering-history identifier to select." }, "sceneIndex": { "minimum": 0, "type": "number", "description": "Zero-based scene index." } }, "required": [ "sceneIndex" ], "type": "object" }, "maxItems": 64, "minItems": 1, "type": "array", "description": "Explicit Studio scene/rendering selections." }, "selectLatest": { "type": "boolean", "description": "Whether Studio should select the latest ready rendering per scene." }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "expectedVersion" ], "type": "object" } ] } }, "application/x-www-form-urlencoded": { "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "expectedVersion": { "description": "Fast compatibility/concurrency guard: when omitted, OmnAPI uses the current MVView.version; explicit stale values are rejected with 409.", "minimum": 0, "type": "number" }, "maxCredits": { "minimum": 0, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "retry": { "type": "boolean", "description": "Whether to retry a supported failed operation." } }, "type": "object" }, { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "expectedVersion": { "description": "Studio optimistic-concurrency guard: the MVView.version this edit is based on; rejected with 409 if the stored version has advanced. Not a platform/task field.", "minimum": 0, "type": "number" }, "maxCredits": { "minimum": 0, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "retry": { "type": "boolean", "description": "Whether to retry a supported failed operation." }, "scenes": { "items": { "properties": { "renderingId": { "minLength": 1, "type": "string", "description": "Scene rendering-history identifier to select." }, "sceneIndex": { "minimum": 0, "type": "number", "description": "Zero-based scene index." } }, "required": [ "sceneIndex" ], "type": "object" }, "maxItems": 64, "minItems": 1, "type": "array", "description": "Explicit Studio scene/rendering selections." }, "selectLatest": { "type": "boolean", "description": "Whether Studio should select the latest ready rendering per scene." }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "expectedVersion" ], "type": "object" } ] } }, "multipart/form-data": { "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "expectedVersion": { "description": "Fast compatibility/concurrency guard: when omitted, OmnAPI uses the current MVView.version; explicit stale values are rejected with 409.", "minimum": 0, "type": "number" }, "maxCredits": { "minimum": 0, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "retry": { "type": "boolean", "description": "Whether to retry a supported failed operation." } }, "type": "object" }, { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "expectedVersion": { "description": "Studio optimistic-concurrency guard: the MVView.version this edit is based on; rejected with 409 if the stored version has advanced. Not a platform/task field.", "minimum": 0, "type": "number" }, "maxCredits": { "minimum": 0, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "retry": { "type": "boolean", "description": "Whether to retry a supported failed operation." }, "scenes": { "items": { "properties": { "renderingId": { "minLength": 1, "type": "string", "description": "Scene rendering-history identifier to select." }, "sceneIndex": { "minimum": 0, "type": "number", "description": "Zero-based scene index." } }, "required": [ "sceneIndex" ], "type": "object" }, "maxItems": 64, "minItems": 1, "type": "array", "description": "Explicit Studio scene/rendering selections." }, "selectLatest": { "type": "boolean", "description": "Whether Studio should select the latest ready rendering per scene." }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "expectedVersion" ], "type": "object" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "compositionHash": { "type": "string" }, "creditsRequired": { "minimum": 0, "type": "number" }, "estimatedCompletionTime": { "anyOf": [ { "anyOf": [ { "description": "Estimated completion time", "type": "Date" }, { "format": "date-time", "type": "string" }, { "format": "date", "type": "string" }, { "type": "number" } ], "description": "Estimated completion time" }, { "type": "null" } ], "nullable": true }, "finalMvId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "idempotent": { "type": "boolean" }, "links": { "additionalProperties": false, "properties": { "final": { "anyOf": [ { "description": "Final downloadable resource URL when available", "type": "string" }, { "type": "null" } ], "nullable": true }, "resource": { "anyOf": [ { "description": "Product resource URL when the product has a dedicated view endpoint", "type": "string" }, { "type": "null" } ], "nullable": true }, "stream": { "description": "Task SSE stream URL for the created task", "type": "string" }, "task": { "description": "Task polling URL for the created task", "type": "string" } }, "required": [ "task", "stream", "resource", "final" ], "type": "object" }, "message": { "type": "string" }, "pricing": { "additionalProperties": false, "properties": { "adjustmentCredits": { "description": "chargedCredits - baseCredits", "type": "number" }, "baseCredits": { "description": "Standard quoted credits before customer pricing adjustment", "type": "number" }, "billingIncrementCredits": { "description": "Smallest customer charge increment", "minimum": 0.0001, "type": "number" }, "calculatedCredits": { "description": "Precise whole-order subtotal before settlement rounding", "type": "number" }, "chargedCredits": { "description": "Credits charged for this create request", "minimum": 0, "type": "number" }, "quoteVersion": { "description": "Pricing quote version stored with the task", "type": "number" }, "settlementPolicyVersion": { "description": "Versioned customer settlement policy", "type": "string" }, "settlementRoundingCredits": { "description": "Whole-order rounding adjustment added at settlement", "minimum": 0, "type": "number" }, "source": { "enum": [ "standard", "customer_rule" ], "type": "string" } }, "required": [ "baseCredits", "chargedCredits", "adjustmentCredits", "source", "quoteVersion" ], "type": "object" }, "product": { "additionalProperties": false, "properties": { "autoFinalize": { "description": "Whether the product should finalize automatically", "type": "boolean" }, "deliveryStatus": { "anyOf": [ { "description": "Product-level delivery status when applicable", "type": "string" }, { "type": "null" } ], "nullable": true }, "featureCode": { "description": "Resolved feature code", "type": "string" }, "modelCode": { "description": "Resolved model code", "type": "string" }, "providerCode": { "description": "Resolved provider code", "type": "string" }, "resourceId": { "anyOf": [ { "description": "Product resource id when created synchronously", "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "description": "Product family for this task, e.g. suno, producer, mv", "type": "string" } }, "required": [ "type", "providerCode", "modelCode", "featureCode", "resourceId" ], "type": "object" }, "requestId": { "anyOf": [ { "description": "Request id echoed from X-Request-Id or generated by API", "type": "string" }, { "type": "null" } ], "nullable": true }, "retryable": { "type": "boolean" }, "status": { "enum": [ "PENDING", "PROCESSING", "READY", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "warningCodes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "taskId", "creditsRequired", "status", "idempotent" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403 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." }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "408": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 408" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 409" }, "413": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 413" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 502" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Finalize MV", "tags": [ "MV" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/mv/{mvId}/lock-character": { "post": { "description": "Attach a public character portrait URL as the Studio character anchor. Requires the MVView.version as expectedVersion and supports quoteId/maxCredits spend confirmation.", "operationId": "postApiV1MvByIdLock_character", "parameters": [ { "in": "path", "name": "mvId", "required": true, "schema": { "type": "string" }, "description": "MV identifier returned by create or read operations." }, { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "characterImage": { "minLength": 1, "type": "string", "description": "Public character reference image URL." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "description": { "maxLength": 500, "type": "string", "description": "Optional customer-facing resource description." }, "expectedVersion": { "description": "Required Studio optimistic-concurrency guard: the MVView.version this edit is based on; rejected with 409 if the stored version has advanced.", "minimum": 0, "type": "number" }, "maxCredits": { "minimum": 0, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." } }, "required": [ "characterImage", "expectedVersion" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "characterImage": { "minLength": 1, "type": "string", "description": "Public character reference image URL." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "description": { "maxLength": 500, "type": "string", "description": "Optional customer-facing resource description." }, "expectedVersion": { "description": "Required Studio optimistic-concurrency guard: the MVView.version this edit is based on; rejected with 409 if the stored version has advanced.", "minimum": 0, "type": "number" }, "maxCredits": { "minimum": 0, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." } }, "required": [ "characterImage", "expectedVersion" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "characterImage": { "minLength": 1, "type": "string", "description": "Public character reference image URL." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "description": { "maxLength": 500, "type": "string", "description": "Optional customer-facing resource description." }, "expectedVersion": { "description": "Required Studio optimistic-concurrency guard: the MVView.version this edit is based on; rejected with 409 if the stored version has advanced.", "minimum": 0, "type": "number" }, "maxCredits": { "minimum": 0, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." } }, "required": [ "characterImage", "expectedVersion" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "creditsRequired": { "minimum": 0, "type": "number" }, "estimatedCompletionTime": { "anyOf": [ { "anyOf": [ { "description": "Estimated completion time", "type": "Date" }, { "format": "date-time", "type": "string" }, { "format": "date", "type": "string" }, { "type": "number" } ], "description": "Estimated completion time" }, { "type": "null" } ], "nullable": true }, "links": { "additionalProperties": false, "properties": { "final": { "anyOf": [ { "description": "Final downloadable resource URL when available", "type": "string" }, { "type": "null" } ], "nullable": true }, "resource": { "anyOf": [ { "description": "Product resource URL when the product has a dedicated view endpoint", "type": "string" }, { "type": "null" } ], "nullable": true }, "stream": { "description": "Task SSE stream URL for the created task", "type": "string" }, "task": { "description": "Task polling URL for the created task", "type": "string" } }, "required": [ "task", "stream", "resource", "final" ], "type": "object" }, "pricing": { "additionalProperties": false, "properties": { "adjustmentCredits": { "description": "chargedCredits - baseCredits", "type": "number" }, "baseCredits": { "description": "Standard quoted credits before customer pricing adjustment", "type": "number" }, "billingIncrementCredits": { "description": "Smallest customer charge increment", "minimum": 0.0001, "type": "number" }, "calculatedCredits": { "description": "Precise whole-order subtotal before settlement rounding", "type": "number" }, "chargedCredits": { "description": "Credits charged for this create request", "minimum": 0, "type": "number" }, "quoteVersion": { "description": "Pricing quote version stored with the task", "type": "number" }, "settlementPolicyVersion": { "description": "Versioned customer settlement policy", "type": "string" }, "settlementRoundingCredits": { "description": "Whole-order rounding adjustment added at settlement", "minimum": 0, "type": "number" }, "source": { "enum": [ "standard", "customer_rule" ], "type": "string" } }, "required": [ "baseCredits", "chargedCredits", "adjustmentCredits", "source", "quoteVersion" ], "type": "object" }, "product": { "additionalProperties": false, "properties": { "autoFinalize": { "description": "Whether the product should finalize automatically", "type": "boolean" }, "deliveryStatus": { "anyOf": [ { "description": "Product-level delivery status when applicable", "type": "string" }, { "type": "null" } ], "nullable": true }, "featureCode": { "description": "Resolved feature code", "type": "string" }, "modelCode": { "description": "Resolved model code", "type": "string" }, "providerCode": { "description": "Resolved provider code", "type": "string" }, "resourceId": { "anyOf": [ { "description": "Product resource id when created synchronously", "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "description": "Product family for this task, e.g. suno, producer, mv", "type": "string" } }, "required": [ "type", "providerCode", "modelCode", "featureCode", "resourceId" ], "type": "object" }, "requestId": { "anyOf": [ { "description": "Request id echoed from X-Request-Id or generated by API", "type": "string" }, { "type": "null" } ], "nullable": true }, "taskId": { "type": "string" }, "warningCodes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "taskId", "creditsRequired", "requestId", "links", "pricing", "product", "warningCodes" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403 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." }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "408": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 408" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 409" }, "413": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 413" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 502" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Lock Studio character anchor", "tags": [ "MV" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/mv/{mvId}/operations": { "get": { "description": "Returns quote/task linkage and charged, refunded, and net credits for this MV.", "operationId": "getApiV1MvByIdOperations", "parameters": [ { "in": "path", "name": "mvId", "required": true, "schema": { "type": "string" }, "description": "MV identifier returned by create or read operations." }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum operation-ledger rows to return." } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "costSummary": { "properties": { "authorizedCredits": { "type": "number" }, "chargedCredits": { "type": "number" }, "netSpentCredits": { "type": "number" }, "operationCount": { "type": "number" }, "refundedCredits": { "type": "number" } }, "required": [ "authorizedCredits", "chargedCredits", "refundedCredits", "netSpentCredits", "operationCount" ], "type": "object" }, "items": { "items": { "properties": { "authorizedCredits": { "type": "number" }, "chargedCredits": { "type": "number" }, "createdAt": { "type": "string" }, "expectedVersion": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "netCredits": { "type": "number" }, "operation": { "type": "string" }, "operationId": { "type": "string" }, "quoteId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "refundedCredits": { "type": "number" }, "settlementStatus": { "enum": [ "PENDING", "CHARGED", "REFUNDED" ], "type": "string" }, "taskId": { "type": "string" }, "taskStatus": { "type": "string" } }, "required": [ "operationId", "operation", "taskId", "quoteId", "expectedVersion", "authorizedCredits", "chargedCredits", "refundedCredits", "netCredits", "settlementStatus", "taskStatus", "createdAt" ], "type": "object" }, "type": "array" } }, "required": [ "items", "costSummary" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "List MV operations and costs", "tags": [ "MV" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/mv/{mvId}/operations/{taskId}/cancel": { "post": { "description": "Cancels and refunds an active MV task before Provider submission. After submission, cancellation succeeds only when the Provider confirms remote cancellation; otherwise the operation remains active and this endpoint returns 409.", "operationId": "postApiV1MvByIdOperationsByTaskIdCancel", "parameters": [ { "in": "path", "name": "mvId", "required": true, "schema": { "type": "string" }, "description": "MV identifier returned by create or read operations." }, { "in": "path", "name": "taskId", "required": true, "schema": { "type": "string" }, "description": "OmnAPI task identifier." } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "providerCancellationSupported": { "type": "boolean" }, "refundedCredits": { "type": "number" }, "status": { "const": "CANCELLED", "type": "string" }, "success": { "type": "boolean" }, "taskId": { "type": "string" } }, "required": [ "success", "taskId", "status", "refundedCredits", "providerCancellationSupported", "message" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "408": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 408" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 409" }, "413": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 413" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 502" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Cancel MV operation", "tags": [ "MV" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/mv/{mvId}/scenes/render-batch": { "post": { "description": "Creates one parent task and one direct-debit charge for 1-30 Studio scenes. Use a render-batch quoteId and maxCredits to confirm the total before execution. Per-scene failures remain individually visible and component usage drives settlement.", "operationId": "postApiV1MvByIdScenesRender_batch", "parameters": [ { "in": "path", "name": "mvId", "required": true, "schema": { "type": "string" }, "description": "MV identifier returned by create or read operations." }, { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "aspectRatio": { "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4" ], "type": "string", "description": "Requested output aspect ratio." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "draft": { "type": "boolean", "description": "Whether to use the supported draft rendering policy." }, "expectedVersion": { "minimum": 0, "type": "number", "description": "Optimistic-concurrency guard using the current resource version." }, "fps": { "enum": [ 24, 48 ], "type": "number", "description": "Requested numeric output frame rate." }, "maxCredits": { "minimum": 0, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "resolution": { "enum": [ "540p", "720p", "1080p" ], "type": "string", "description": "Requested output resolution." }, "sceneIndexes": { "items": { "minimum": 0, "type": "number" }, "maxItems": 30, "minItems": 1, "type": "array", "uniqueItems": true, "description": "Unique zero-based scene indexes included in the operation." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoProvider": { "enum": [ "p-video", "hailuo", "vidu" ], "type": "string", "description": "Public scene-video option code." } }, "required": [ "sceneIndexes", "expectedVersion" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "aspectRatio": { "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4" ], "type": "string", "description": "Requested output aspect ratio." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "draft": { "type": "boolean", "description": "Whether to use the supported draft rendering policy." }, "expectedVersion": { "minimum": 0, "type": "number", "description": "Optimistic-concurrency guard using the current resource version." }, "fps": { "enum": [ 24, 48 ], "type": "string", "description": "Requested numeric output frame rate." }, "maxCredits": { "minimum": 0, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "resolution": { "enum": [ "540p", "720p", "1080p" ], "type": "string", "description": "Requested output resolution." }, "sceneIndexes": { "items": { "minimum": 0, "type": "number" }, "maxItems": 30, "minItems": 1, "type": "array", "uniqueItems": true, "description": "Unique zero-based scene indexes included in the operation." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoProvider": { "enum": [ "p-video", "hailuo", "vidu" ], "type": "string", "description": "Public scene-video option code." } }, "required": [ "sceneIndexes", "expectedVersion" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "aspectRatio": { "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4" ], "type": "string", "description": "Requested output aspect ratio." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "draft": { "type": "boolean", "description": "Whether to use the supported draft rendering policy." }, "expectedVersion": { "minimum": 0, "type": "number", "description": "Optimistic-concurrency guard using the current resource version." }, "fps": { "enum": [ 24, 48 ], "type": "string", "description": "Requested numeric output frame rate." }, "maxCredits": { "minimum": 0, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "resolution": { "enum": [ "540p", "720p", "1080p" ], "type": "string", "description": "Requested output resolution." }, "sceneIndexes": { "items": { "minimum": 0, "type": "number" }, "maxItems": 30, "minItems": 1, "type": "array", "uniqueItems": true, "description": "Unique zero-based scene indexes included in the operation." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoProvider": { "enum": [ "p-video", "hailuo", "vidu" ], "type": "string", "description": "Public scene-video option code." } }, "required": [ "sceneIndexes", "expectedVersion" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "creditsRequired": { "minimum": 0, "type": "number" }, "estimatedCompletionTime": { "anyOf": [ { "anyOf": [ { "description": "Estimated completion time", "type": "Date" }, { "format": "date-time", "type": "string" }, { "format": "date", "type": "string" }, { "type": "number" } ], "description": "Estimated completion time" }, { "type": "null" } ], "nullable": true }, "links": { "additionalProperties": false, "properties": { "final": { "anyOf": [ { "description": "Final downloadable resource URL when available", "type": "string" }, { "type": "null" } ], "nullable": true }, "resource": { "anyOf": [ { "description": "Product resource URL when the product has a dedicated view endpoint", "type": "string" }, { "type": "null" } ], "nullable": true }, "stream": { "description": "Task SSE stream URL for the created task", "type": "string" }, "task": { "description": "Task polling URL for the created task", "type": "string" } }, "required": [ "task", "stream", "resource", "final" ], "type": "object" }, "pricing": { "additionalProperties": false, "properties": { "adjustmentCredits": { "description": "chargedCredits - baseCredits", "type": "number" }, "baseCredits": { "description": "Standard quoted credits before customer pricing adjustment", "type": "number" }, "billingIncrementCredits": { "description": "Smallest customer charge increment", "minimum": 0.0001, "type": "number" }, "calculatedCredits": { "description": "Precise whole-order subtotal before settlement rounding", "type": "number" }, "chargedCredits": { "description": "Credits charged for this create request", "minimum": 0, "type": "number" }, "quoteVersion": { "description": "Pricing quote version stored with the task", "type": "number" }, "settlementPolicyVersion": { "description": "Versioned customer settlement policy", "type": "string" }, "settlementRoundingCredits": { "description": "Whole-order rounding adjustment added at settlement", "minimum": 0, "type": "number" }, "source": { "enum": [ "standard", "customer_rule" ], "type": "string" } }, "required": [ "baseCredits", "chargedCredits", "adjustmentCredits", "source", "quoteVersion" ], "type": "object" }, "product": { "additionalProperties": false, "properties": { "autoFinalize": { "description": "Whether the product should finalize automatically", "type": "boolean" }, "deliveryStatus": { "anyOf": [ { "description": "Product-level delivery status when applicable", "type": "string" }, { "type": "null" } ], "nullable": true }, "featureCode": { "description": "Resolved feature code", "type": "string" }, "modelCode": { "description": "Resolved model code", "type": "string" }, "providerCode": { "description": "Resolved provider code", "type": "string" }, "resourceId": { "anyOf": [ { "description": "Product resource id when created synchronously", "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "description": "Product family for this task, e.g. suno, producer, mv", "type": "string" } }, "required": [ "type", "providerCode", "modelCode", "featureCode", "resourceId" ], "type": "object" }, "requestId": { "anyOf": [ { "description": "Request id echoed from X-Request-Id or generated by API", "type": "string" }, { "type": "null" } ], "nullable": true }, "sceneIndexes": { "items": { "type": "number" }, "type": "array" }, "taskId": { "type": "string" }, "warningCodes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "taskId", "sceneIndexes", "creditsRequired", "requestId", "links", "pricing", "product", "warningCodes" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403 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." }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "408": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 408" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 409" }, "413": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 413" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 502" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Render multiple Studio scenes", "tags": [ "MV" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/mv/{mvId}/scenes/{sceneIndex}": { "patch": { "description": "Persistently edits Studio prompts, framing, mood, lyrics window, or timing. The backend invalidates dependent image/video/final assets and increments both scene and MV versions.", "operationId": "patchApiV1MvByIdScenesByIdx", "parameters": [ { "in": "path", "name": "mvId", "required": true, "schema": { "type": "string" }, "description": "MV identifier returned by create or read operations." }, { "in": "path", "name": "sceneIndex", "required": true, "schema": { "type": "string" }, "description": "Zero-based scene index from the MV storyboard." } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "expectedVersion": { "minimum": 0, "type": "number", "description": "Optimistic-concurrency guard using the current resource version." }, "framing": { "maxLength": 300, "type": "string", "description": "Persistent scene framing direction." }, "imagePrompt": { "maxLength": 1500, "minLength": 1, "type": "string", "description": "Image-generation or persistent scene-image instruction." }, "lighting": { "maxLength": 300, "type": "string", "description": "Persistent scene lighting direction." }, "lyricsWindow": { "maxLength": 1000, "type": "string", "description": "Lyric context associated with this scene." }, "mood": { "maxLength": 300, "type": "string", "description": "Requested musical or visual mood." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." }, "videoPrompt": { "maxLength": 1500, "minLength": 1, "type": "string", "description": "Persistent or one-shot scene-video instruction." } }, "required": [ "expectedVersion" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "expectedVersion": { "minimum": 0, "type": "number", "description": "Optimistic-concurrency guard using the current resource version." }, "framing": { "maxLength": 300, "type": "string", "description": "Persistent scene framing direction." }, "imagePrompt": { "maxLength": 1500, "minLength": 1, "type": "string", "description": "Image-generation or persistent scene-image instruction." }, "lighting": { "maxLength": 300, "type": "string", "description": "Persistent scene lighting direction." }, "lyricsWindow": { "maxLength": 1000, "type": "string", "description": "Lyric context associated with this scene." }, "mood": { "maxLength": 300, "type": "string", "description": "Requested musical or visual mood." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." }, "videoPrompt": { "maxLength": 1500, "minLength": 1, "type": "string", "description": "Persistent or one-shot scene-video instruction." } }, "required": [ "expectedVersion" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "expectedVersion": { "minimum": 0, "type": "number", "description": "Optimistic-concurrency guard using the current resource version." }, "framing": { "maxLength": 300, "type": "string", "description": "Persistent scene framing direction." }, "imagePrompt": { "maxLength": 1500, "minLength": 1, "type": "string", "description": "Image-generation or persistent scene-image instruction." }, "lighting": { "maxLength": 300, "type": "string", "description": "Persistent scene lighting direction." }, "lyricsWindow": { "maxLength": 1000, "type": "string", "description": "Lyric context associated with this scene." }, "mood": { "maxLength": 300, "type": "string", "description": "Requested musical or visual mood." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." }, "videoPrompt": { "maxLength": 1500, "minLength": 1, "type": "string", "description": "Persistent or one-shot scene-video instruction." } }, "required": [ "expectedVersion" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "finalizationRequired": { "type": "boolean" }, "invalidated": { "items": { "type": "string" }, "type": "array" }, "mvId": { "type": "string" }, "requiresImageRegeneration": { "type": "boolean" }, "sceneIndex": { "type": "number" }, "sceneVersion": { "type": "number" }, "version": { "type": "number" } }, "required": [ "mvId", "sceneIndex", "version", "sceneVersion", "invalidated", "requiresImageRegeneration", "finalizationRequired" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "408": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 408" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 409" }, "413": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 413" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 502" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Edit Studio scene", "tags": [ "MV" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/mv/{mvId}/scenes/{sceneIndex}/regenerate-image": { "post": { "description": "Regenerate one Studio scene still image without changing the rest of the storyboard. Requires the MVView.version as expectedVersion.", "operationId": "postApiV1MvByIdScenesByIdxRegenerate_image", "parameters": [ { "in": "path", "name": "mvId", "required": true, "schema": { "type": "string" }, "description": "MV identifier returned by create or read operations." }, { "in": "path", "name": "sceneIndex", "required": true, "schema": { "type": "string" }, "description": "Zero-based scene index from the MV storyboard." }, { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "expectedVersion": { "description": "Studio optimistic-concurrency guard: the MVView.version this edit is based on; rejected with 409 if the stored version has advanced. Not a platform/task field.", "minimum": 0, "type": "number" }, "imagePrompt": { "maxLength": 1500, "type": "string", "description": "Image-generation or persistent scene-image instruction." }, "imagePromptOverride": { "maxLength": 1500, "type": "string", "description": "One-shot scene-image prompt override." }, "maxCredits": { "minimum": 0, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." } }, "required": [ "expectedVersion" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "expectedVersion": { "description": "Studio optimistic-concurrency guard: the MVView.version this edit is based on; rejected with 409 if the stored version has advanced. Not a platform/task field.", "minimum": 0, "type": "number" }, "imagePrompt": { "maxLength": 1500, "type": "string", "description": "Image-generation or persistent scene-image instruction." }, "imagePromptOverride": { "maxLength": 1500, "type": "string", "description": "One-shot scene-image prompt override." }, "maxCredits": { "minimum": 0, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." } }, "required": [ "expectedVersion" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "expectedVersion": { "description": "Studio optimistic-concurrency guard: the MVView.version this edit is based on; rejected with 409 if the stored version has advanced. Not a platform/task field.", "minimum": 0, "type": "number" }, "imagePrompt": { "maxLength": 1500, "type": "string", "description": "Image-generation or persistent scene-image instruction." }, "imagePromptOverride": { "maxLength": 1500, "type": "string", "description": "One-shot scene-image prompt override." }, "maxCredits": { "minimum": 0, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." } }, "required": [ "expectedVersion" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "creditsRequired": { "minimum": 0, "type": "number" }, "estimatedCompletionTime": { "anyOf": [ { "anyOf": [ { "description": "Estimated completion time", "type": "Date" }, { "format": "date-time", "type": "string" }, { "format": "date", "type": "string" }, { "type": "number" } ], "description": "Estimated completion time" }, { "type": "null" } ], "nullable": true }, "links": { "additionalProperties": false, "properties": { "final": { "anyOf": [ { "description": "Final downloadable resource URL when available", "type": "string" }, { "type": "null" } ], "nullable": true }, "resource": { "anyOf": [ { "description": "Product resource URL when the product has a dedicated view endpoint", "type": "string" }, { "type": "null" } ], "nullable": true }, "stream": { "description": "Task SSE stream URL for the created task", "type": "string" }, "task": { "description": "Task polling URL for the created task", "type": "string" } }, "required": [ "task", "stream", "resource", "final" ], "type": "object" }, "pricing": { "additionalProperties": false, "properties": { "adjustmentCredits": { "description": "chargedCredits - baseCredits", "type": "number" }, "baseCredits": { "description": "Standard quoted credits before customer pricing adjustment", "type": "number" }, "billingIncrementCredits": { "description": "Smallest customer charge increment", "minimum": 0.0001, "type": "number" }, "calculatedCredits": { "description": "Precise whole-order subtotal before settlement rounding", "type": "number" }, "chargedCredits": { "description": "Credits charged for this create request", "minimum": 0, "type": "number" }, "quoteVersion": { "description": "Pricing quote version stored with the task", "type": "number" }, "settlementPolicyVersion": { "description": "Versioned customer settlement policy", "type": "string" }, "settlementRoundingCredits": { "description": "Whole-order rounding adjustment added at settlement", "minimum": 0, "type": "number" }, "source": { "enum": [ "standard", "customer_rule" ], "type": "string" } }, "required": [ "baseCredits", "chargedCredits", "adjustmentCredits", "source", "quoteVersion" ], "type": "object" }, "product": { "additionalProperties": false, "properties": { "autoFinalize": { "description": "Whether the product should finalize automatically", "type": "boolean" }, "deliveryStatus": { "anyOf": [ { "description": "Product-level delivery status when applicable", "type": "string" }, { "type": "null" } ], "nullable": true }, "featureCode": { "description": "Resolved feature code", "type": "string" }, "modelCode": { "description": "Resolved model code", "type": "string" }, "providerCode": { "description": "Resolved provider code", "type": "string" }, "resourceId": { "anyOf": [ { "description": "Product resource id when created synchronously", "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "description": "Product family for this task, e.g. suno, producer, mv", "type": "string" } }, "required": [ "type", "providerCode", "modelCode", "featureCode", "resourceId" ], "type": "object" }, "requestId": { "anyOf": [ { "description": "Request id echoed from X-Request-Id or generated by API", "type": "string" }, { "type": "null" } ], "nullable": true }, "taskId": { "type": "string" }, "warningCodes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "taskId", "creditsRequired", "requestId", "links", "pricing", "product", "warningCodes" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403 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." }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "408": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 408" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 409" }, "413": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 413" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 502" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Regenerate Studio scene image", "tags": [ "MV" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/mv/{mvId}/scenes/{sceneIndex}/render": { "post": { "description": "Render one MV scene. Studio creates a candidate scene video from the current scene image and requires MVView.version as expectedVersion. Fast edits the currently selected generated scene and accepts prompt, optional referenceImages replacement, expectedVersion, config, and prompt compatibility aliases. Omitting referenceImages preserves the source scene images. Fast rejects durationSec/resolution/render controls; scene-edit billing uses saved Fast scene metadata.", "operationId": "postApiV1MvByIdScenesByIdxRender", "parameters": [ { "in": "path", "name": "mvId", "required": true, "schema": { "type": "string" }, "description": "MV identifier returned by create or read operations." }, { "in": "path", "name": "sceneIndex", "required": true, "schema": { "type": "string" }, "description": "Zero-based scene index from the MV storyboard." }, { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "aspectRatio": { "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4" ], "type": "string", "description": "Requested output aspect ratio." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "draft": { "type": "boolean", "description": "Whether to use the supported draft rendering policy." }, "durationSec": { "description": "Studio-only render control. Fast scene edit rejects client-supplied durationSec; Fast scene-edit billing uses saved scene metadata.", "maximum": 16, "minimum": 1, "type": "number" }, "expectedVersion": { "description": "Optimistic-concurrency guard. Fast may omit it for backward compatibility; if omitted, OmnAPI uses the latest MV version available when the request is accepted. Studio requires it and rejects stale values with 409.", "minimum": 0, "type": "number" }, "fps": { "enum": [ 24, 48 ], "type": "number", "description": "Requested numeric output frame rate." }, "maxCredits": { "minimum": 0, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "prompt": { "description": "Cross-mode prompt. Fast scene edit uses this as the official instruction field; Studio treats it as a one-shot video prompt override.", "maxLength": 3000, "type": "string" }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "referenceImages": { "items": { "minLength": 1, "type": "string" }, "maxItems": 7, "minItems": 1, "type": "array", "description": "Public reference image URLs." }, "resolution": { "enum": [ "540p", "720p", "1080p" ], "type": "string", "description": "Requested output resolution." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoPrompt": { "description": "Alias of videoPromptOverride for Studio. Fast accepts this only as a compatibility alias for prompt.", "maxLength": 1500, "type": "string" }, "videoPromptOverride": { "description": "Studio one-shot video prompt override. Fast accepts this only as a compatibility alias for prompt.", "maxLength": 1500, "type": "string" }, "videoProvider": { "enum": [ "p-video", "hailuo", "vidu" ], "type": "string", "description": "Public scene-video option code." } }, "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "aspectRatio": { "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4" ], "type": "string", "description": "Requested output aspect ratio." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "draft": { "type": "boolean", "description": "Whether to use the supported draft rendering policy." }, "durationSec": { "description": "Studio-only render control. Fast scene edit rejects client-supplied durationSec; Fast scene-edit billing uses saved scene metadata.", "maximum": 16, "minimum": 1, "type": "number" }, "expectedVersion": { "description": "Optimistic-concurrency guard. Fast may omit it for backward compatibility; if omitted, OmnAPI uses the latest MV version available when the request is accepted. Studio requires it and rejects stale values with 409.", "minimum": 0, "type": "number" }, "fps": { "enum": [ 24, 48 ], "type": "string", "description": "Requested numeric output frame rate." }, "maxCredits": { "minimum": 0, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "prompt": { "description": "Cross-mode prompt. Fast scene edit uses this as the official instruction field; Studio treats it as a one-shot video prompt override.", "maxLength": 3000, "type": "string" }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "referenceImages": { "items": { "minLength": 1, "type": "string" }, "maxItems": 7, "minItems": 1, "type": "array", "description": "Public reference image URLs." }, "resolution": { "enum": [ "540p", "720p", "1080p" ], "type": "string", "description": "Requested output resolution." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoPrompt": { "description": "Alias of videoPromptOverride for Studio. Fast accepts this only as a compatibility alias for prompt.", "maxLength": 1500, "type": "string" }, "videoPromptOverride": { "description": "Studio one-shot video prompt override. Fast accepts this only as a compatibility alias for prompt.", "maxLength": 1500, "type": "string" }, "videoProvider": { "enum": [ "p-video", "hailuo", "vidu" ], "type": "string", "description": "Public scene-video option code." } }, "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "aspectRatio": { "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4" ], "type": "string", "description": "Requested output aspect ratio." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "draft": { "type": "boolean", "description": "Whether to use the supported draft rendering policy." }, "durationSec": { "description": "Studio-only render control. Fast scene edit rejects client-supplied durationSec; Fast scene-edit billing uses saved scene metadata.", "maximum": 16, "minimum": 1, "type": "number" }, "expectedVersion": { "description": "Optimistic-concurrency guard. Fast may omit it for backward compatibility; if omitted, OmnAPI uses the latest MV version available when the request is accepted. Studio requires it and rejects stale values with 409.", "minimum": 0, "type": "number" }, "fps": { "enum": [ 24, 48 ], "type": "string", "description": "Requested numeric output frame rate." }, "maxCredits": { "minimum": 0, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "prompt": { "description": "Cross-mode prompt. Fast scene edit uses this as the official instruction field; Studio treats it as a one-shot video prompt override.", "maxLength": 3000, "type": "string" }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "referenceImages": { "items": { "minLength": 1, "type": "string" }, "maxItems": 7, "minItems": 1, "type": "array", "description": "Public reference image URLs." }, "resolution": { "enum": [ "540p", "720p", "1080p" ], "type": "string", "description": "Requested output resolution." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoPrompt": { "description": "Alias of videoPromptOverride for Studio. Fast accepts this only as a compatibility alias for prompt.", "maxLength": 1500, "type": "string" }, "videoPromptOverride": { "description": "Studio one-shot video prompt override. Fast accepts this only as a compatibility alias for prompt.", "maxLength": 1500, "type": "string" }, "videoProvider": { "enum": [ "p-video", "hailuo", "vidu" ], "type": "string", "description": "Public scene-video option code." } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "charged": { "type": "boolean" }, "creditsRequired": { "minimum": 0, "type": "number" }, "estimatedCompletionTime": { "anyOf": [ { "anyOf": [ { "description": "Estimated completion time", "type": "Date" }, { "format": "date-time", "type": "string" }, { "format": "date", "type": "string" }, { "type": "number" } ], "description": "Estimated completion time" }, { "type": "null" } ], "nullable": true }, "links": { "additionalProperties": false, "properties": { "final": { "anyOf": [ { "description": "Final downloadable resource URL when available", "type": "string" }, { "type": "null" } ], "nullable": true }, "resource": { "anyOf": [ { "description": "Product resource URL when the product has a dedicated view endpoint", "type": "string" }, { "type": "null" } ], "nullable": true }, "stream": { "description": "Task SSE stream URL for the created task", "type": "string" }, "task": { "description": "Task polling URL for the created task", "type": "string" } }, "required": [ "task", "stream", "resource", "final" ], "type": "object" }, "pricing": { "additionalProperties": false, "properties": { "adjustmentCredits": { "description": "chargedCredits - baseCredits", "type": "number" }, "baseCredits": { "description": "Standard quoted credits before customer pricing adjustment", "type": "number" }, "billingIncrementCredits": { "description": "Smallest customer charge increment", "minimum": 0.0001, "type": "number" }, "calculatedCredits": { "description": "Precise whole-order subtotal before settlement rounding", "type": "number" }, "chargedCredits": { "description": "Credits charged for this create request", "minimum": 0, "type": "number" }, "quoteVersion": { "description": "Pricing quote version stored with the task", "type": "number" }, "settlementPolicyVersion": { "description": "Versioned customer settlement policy", "type": "string" }, "settlementRoundingCredits": { "description": "Whole-order rounding adjustment added at settlement", "minimum": 0, "type": "number" }, "source": { "enum": [ "standard", "customer_rule" ], "type": "string" } }, "required": [ "baseCredits", "chargedCredits", "adjustmentCredits", "source", "quoteVersion" ], "type": "object" }, "product": { "additionalProperties": false, "properties": { "autoFinalize": { "description": "Whether the product should finalize automatically", "type": "boolean" }, "deliveryStatus": { "anyOf": [ { "description": "Product-level delivery status when applicable", "type": "string" }, { "type": "null" } ], "nullable": true }, "featureCode": { "description": "Resolved feature code", "type": "string" }, "modelCode": { "description": "Resolved model code", "type": "string" }, "providerCode": { "description": "Resolved provider code", "type": "string" }, "resourceId": { "anyOf": [ { "description": "Product resource id when created synchronously", "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "description": "Product family for this task, e.g. suno, producer, mv", "type": "string" } }, "required": [ "type", "providerCode", "modelCode", "featureCode", "resourceId" ], "type": "object" }, "renderingId": { "type": "string" }, "requestId": { "anyOf": [ { "description": "Request id echoed from X-Request-Id or generated by API", "type": "string" }, { "type": "null" } ], "nullable": true }, "sceneIndex": { "type": "number" }, "taskId": { "type": "string" }, "version": { "type": "number" }, "warningCodes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "taskId", "creditsRequired", "requestId", "links", "pricing", "product", "warningCodes" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403 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." }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "408": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 408" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 409" }, "413": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 413" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 502" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Render MV scene", "tags": [ "MV" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/mv/{mvId}/scenes/{sceneIndex}/select-rendering": { "patch": { "description": "Choose which completed scene rendering should be used by finalization. Fast uses MVView.scenes[].renderingHistory[].id and recomposes selected Vidu jobs; Studio selects the storyboard rendering. Requires the MVView.version as expectedVersion.", "operationId": "patchApiV1MvByIdScenesByIdxSelect_rendering", "parameters": [ { "in": "path", "name": "mvId", "required": true, "schema": { "type": "string" }, "description": "MV identifier returned by create or read operations." }, { "in": "path", "name": "sceneIndex", "required": true, "schema": { "type": "string" }, "description": "Zero-based scene index from the MV storyboard." } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expectedVersion": { "description": "MV optimistic-concurrency guard: the MVView.version this selection is based on; rejected with 409 if the stored version has advanced. Not a platform/task field.", "minimum": 0, "type": "number" }, "renderingId": { "minLength": 1, "type": "string", "description": "Scene rendering-history identifier to select." } }, "required": [ "renderingId", "expectedVersion" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "expectedVersion": { "description": "MV optimistic-concurrency guard: the MVView.version this selection is based on; rejected with 409 if the stored version has advanced. Not a platform/task field.", "minimum": 0, "type": "number" }, "renderingId": { "minLength": 1, "type": "string", "description": "Scene rendering-history identifier to select." } }, "required": [ "renderingId", "expectedVersion" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "expectedVersion": { "description": "MV optimistic-concurrency guard: the MVView.version this selection is based on; rejected with 409 if the stored version has advanced. Not a platform/task field.", "minimum": 0, "type": "number" }, "renderingId": { "minLength": 1, "type": "string", "description": "Scene rendering-history identifier to select." } }, "required": [ "renderingId", "expectedVersion" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "finalizationRequired": { "type": "boolean" }, "finalizeAction": { "anyOf": [ { "const": "recompose", "type": "string" }, { "type": "null" } ], "nullable": true }, "mvId": { "type": "string" }, "sceneIndex": { "type": "number" }, "selectedRenderingId": { "type": "string" }, "staleReason": { "anyOf": [ { "anyOf": [ { "const": "missing_final", "type": "string" }, { "const": "final_processing", "type": "string" }, { "const": "final_expired", "type": "string" }, { "const": "source_rendering", "type": "string" }, { "const": "source_failed", "type": "string" }, { "const": "source_changed", "type": "string" }, { "const": "composition_unknown", "type": "string" }, { "const": "url_unavailable", "type": "string" } ] }, { "type": "null" } ], "nullable": true }, "storyboardId": { "type": "string" }, "version": { "type": "number" } }, "required": [ "mvId", "sceneIndex", "selectedRenderingId", "version" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "408": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 408" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 409" }, "413": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 413" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 502" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Select scene rendering", "tags": [ "MV" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/pricing/catalog": { "get": { "description": "Returns the public pricing catalog used by omnapi.com and docs. The catalog is generated from the same runtime pricing functions used for task credit deduction.", "operationId": "getApiV1PricingCatalog", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "apiPricingDetails": { "items": { "additionalProperties": false, "properties": { "allowedValues": { "items": { "type": "string" }, "type": "array" }, "apiName": { "type": "string" }, "billingUnit": { "type": "string" }, "costLabel": { "type": "string" }, "credits": { "type": "number" }, "creditsLabel": { "type": "string" }, "endpoint": { "type": "string" }, "exampleLabel": { "type": "string" }, "id": { "type": "string" }, "model": { "type": "string" }, "notes": { "type": "string" }, "operation": { "type": "string" }, "parameters": { "type": "string" }, "pricingFormula": { "additionalProperties": false, "properties": { "creditsPerUnit": { "type": "number" }, "defaultCostGuardUsdPerUnit": { "type": "number" }, "kind": { "const": "duration", "type": "string" }, "minimumCredits": { "type": "number" }, "referenceUsdPerUnit": { "type": "number" }, "unitSeconds": { "type": "number" } }, "required": [ "kind", "unitSeconds", "creditsPerUnit", "minimumCredits", "referenceUsdPerUnit", "defaultCostGuardUsdPerUnit" ], "type": "object" }, "productLine": { "type": "string" }, "sourceBasis": { "type": "string" } }, "required": [ "id", "productLine", "apiName", "operation", "endpoint", "billingUnit" ], "type": "object" }, "type": "array" }, "apiProducts": { "items": { "additionalProperties": false, "properties": { "category": { "type": "string" }, "costLabel": { "type": "string" }, "creditsLabel": { "type": "string" }, "creditsPerRequest": { "type": "number" }, "description": { "type": "string" }, "docsPath": { "type": "string" }, "icon": { "type": "string" }, "id": { "type": "string" }, "includeInUsageExamples": { "type": "boolean" }, "name": { "type": "string" }, "usageUnitLabel": { "type": "string" } }, "required": [ "id", "name", "category", "description", "icon" ], "type": "object" }, "type": "array" }, "checkoutFeeBps": { "minimum": 0, "multipleOf": 1, "type": "number" }, "creditPackages": { "items": { "additionalProperties": false, "properties": { "credits": { "type": "number" }, "description": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "price": { "description": "Package price in USD.", "type": "number" } }, "required": [ "id", "credits", "price", "name", "description" ], "type": "object" }, "type": "array" }, "creditsExpirationYears": { "minimum": 0, "type": "number" }, "updatedAt": { "description": "Catalog effective date in YYYY-MM-DD format.", "format": "date", "type": "string" }, "version": { "description": "Immutable pricing-catalog version.", "type": "string" }, "welcomeCredits": { "minimum": 0, "type": "number" } }, "required": [ "version", "updatedAt", "creditPackages", "apiProducts", "apiPricingDetails", "checkoutFeeBps", "creditsExpirationYears", "welcomeCredits" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "description": "Public IP protection.", "schema": { "enum": [ "ip" ], "type": "string" } }, "X-RateLimit-Type": { "description": "IP protection window.", "schema": { "enum": [ "window" ], "type": "string" } } } }, "429": { "$ref": "#/components/responses/OmnapiIpRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "Get public pricing catalog", "tags": [ "Pricing" ], "security": [] } }, "/api/v1/producer/generate/image": { "post": { "description": "Create an image generation task using Producer service.", "operationId": "postApiV1ProducerGenerateImage", "parameters": [ { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "prompt": { "description": "Image generation prompt", "maxLength": 2000, "type": "string" } }, "required": [ "prompt" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "prompt": { "description": "Image generation prompt", "maxLength": 2000, "type": "string" } }, "required": [ "prompt" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "prompt": { "description": "Image generation prompt", "maxLength": 2000, "type": "string" } }, "required": [ "prompt" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsRequired": { "description": "Exact credits deducted to start the task", "minimum": 0, "type": "number" }, "estimatedCompletionTime": { "anyOf": [ { "anyOf": [ { "description": "Estimated completion time", "type": "Date" }, { "format": "date-time", "type": "string" }, { "format": "date", "type": "string" }, { "type": "number" } ], "description": "Estimated completion time" }, { "type": "null" } ], "nullable": true }, "links": { "additionalProperties": false, "properties": { "final": { "anyOf": [ { "description": "Final downloadable resource URL when available", "type": "string" }, { "type": "null" } ], "nullable": true }, "resource": { "anyOf": [ { "description": "Product resource URL when the product has a dedicated view endpoint", "type": "string" }, { "type": "null" } ], "nullable": true }, "stream": { "description": "Task SSE stream URL for the created task", "type": "string" }, "task": { "description": "Task polling URL for the created task", "type": "string" } }, "required": [ "task", "stream", "resource", "final" ], "type": "object" }, "pricing": { "additionalProperties": false, "properties": { "adjustmentCredits": { "description": "chargedCredits - baseCredits", "type": "number" }, "baseCredits": { "description": "Standard quoted credits before customer pricing adjustment", "type": "number" }, "billingIncrementCredits": { "description": "Smallest customer charge increment", "minimum": 0.0001, "type": "number" }, "calculatedCredits": { "description": "Precise whole-order subtotal before settlement rounding", "type": "number" }, "chargedCredits": { "description": "Credits charged for this create request", "minimum": 0, "type": "number" }, "quoteVersion": { "description": "Pricing quote version stored with the task", "type": "number" }, "settlementPolicyVersion": { "description": "Versioned customer settlement policy", "type": "string" }, "settlementRoundingCredits": { "description": "Whole-order rounding adjustment added at settlement", "minimum": 0, "type": "number" }, "source": { "enum": [ "standard", "customer_rule" ], "type": "string" } }, "required": [ "baseCredits", "chargedCredits", "adjustmentCredits", "source", "quoteVersion" ], "type": "object" }, "product": { "additionalProperties": false, "properties": { "autoFinalize": { "description": "Whether the product should finalize automatically", "type": "boolean" }, "deliveryStatus": { "anyOf": [ { "description": "Product-level delivery status when applicable", "type": "string" }, { "type": "null" } ], "nullable": true }, "featureCode": { "description": "Resolved feature code", "type": "string" }, "modelCode": { "description": "Resolved model code", "type": "string" }, "providerCode": { "description": "Resolved provider code", "type": "string" }, "resourceId": { "anyOf": [ { "description": "Product resource id when created synchronously", "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "description": "Product family for this task, e.g. suno, producer, mv", "type": "string" } }, "required": [ "type", "providerCode", "modelCode", "featureCode", "resourceId" ], "type": "object" }, "requestId": { "anyOf": [ { "description": "Request id echoed from X-Request-Id or generated by API", "type": "string" }, { "type": "null" } ], "nullable": true }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "description": "Task unique identifier", "type": "string" }, "warningCodes": { "items": { "description": "Non-fatal request warnings", "type": "string" }, "type": "array" } }, "required": [ "taskId", "status", "creditsRequired", "requestId", "links", "pricing", "product", "warningCodes" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "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." }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "Generate Image", "tags": [ "Producer" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/producer/generate/lyrics": { "post": { "description": "Create a lyrics generation task using Producer service.", "operationId": "postApiV1ProducerGenerateLyrics", "parameters": [ { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "prompt": { "description": "Text prompt for lyrics generation", "maxLength": 3000, "type": "string" } }, "required": [ "prompt" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "prompt": { "description": "Text prompt for lyrics generation", "maxLength": 3000, "type": "string" } }, "required": [ "prompt" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "prompt": { "description": "Text prompt for lyrics generation", "maxLength": 3000, "type": "string" } }, "required": [ "prompt" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsRequired": { "description": "Exact credits deducted to start the task", "minimum": 0, "type": "number" }, "estimatedCompletionTime": { "anyOf": [ { "anyOf": [ { "description": "Estimated completion time", "type": "Date" }, { "format": "date-time", "type": "string" }, { "format": "date", "type": "string" }, { "type": "number" } ], "description": "Estimated completion time" }, { "type": "null" } ], "nullable": true }, "links": { "additionalProperties": false, "properties": { "final": { "anyOf": [ { "description": "Final downloadable resource URL when available", "type": "string" }, { "type": "null" } ], "nullable": true }, "resource": { "anyOf": [ { "description": "Product resource URL when the product has a dedicated view endpoint", "type": "string" }, { "type": "null" } ], "nullable": true }, "stream": { "description": "Task SSE stream URL for the created task", "type": "string" }, "task": { "description": "Task polling URL for the created task", "type": "string" } }, "required": [ "task", "stream", "resource", "final" ], "type": "object" }, "pricing": { "additionalProperties": false, "properties": { "adjustmentCredits": { "description": "chargedCredits - baseCredits", "type": "number" }, "baseCredits": { "description": "Standard quoted credits before customer pricing adjustment", "type": "number" }, "billingIncrementCredits": { "description": "Smallest customer charge increment", "minimum": 0.0001, "type": "number" }, "calculatedCredits": { "description": "Precise whole-order subtotal before settlement rounding", "type": "number" }, "chargedCredits": { "description": "Credits charged for this create request", "minimum": 0, "type": "number" }, "quoteVersion": { "description": "Pricing quote version stored with the task", "type": "number" }, "settlementPolicyVersion": { "description": "Versioned customer settlement policy", "type": "string" }, "settlementRoundingCredits": { "description": "Whole-order rounding adjustment added at settlement", "minimum": 0, "type": "number" }, "source": { "enum": [ "standard", "customer_rule" ], "type": "string" } }, "required": [ "baseCredits", "chargedCredits", "adjustmentCredits", "source", "quoteVersion" ], "type": "object" }, "product": { "additionalProperties": false, "properties": { "autoFinalize": { "description": "Whether the product should finalize automatically", "type": "boolean" }, "deliveryStatus": { "anyOf": [ { "description": "Product-level delivery status when applicable", "type": "string" }, { "type": "null" } ], "nullable": true }, "featureCode": { "description": "Resolved feature code", "type": "string" }, "modelCode": { "description": "Resolved model code", "type": "string" }, "providerCode": { "description": "Resolved provider code", "type": "string" }, "resourceId": { "anyOf": [ { "description": "Product resource id when created synchronously", "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "description": "Product family for this task, e.g. suno, producer, mv", "type": "string" } }, "required": [ "type", "providerCode", "modelCode", "featureCode", "resourceId" ], "type": "object" }, "requestId": { "anyOf": [ { "description": "Request id echoed from X-Request-Id or generated by API", "type": "string" }, { "type": "null" } ], "nullable": true }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "description": "Task unique identifier", "type": "string" }, "warningCodes": { "items": { "description": "Non-fatal request warnings", "type": "string" }, "type": "array" } }, "required": [ "taskId", "status", "creditsRequired", "requestId", "links", "pricing", "product", "warningCodes" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "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." }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "Generate Lyrics", "tags": [ "Producer" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/producer/generate/music/compose": { "post": { "description": "Queue a Producer compose task: supports lyrics/instrumental, sound prompt, seed/bpm/length, title, and optional cover image.", "operationId": "postApiV1ProducerGenerateMusicCompose", "parameters": [ { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "advancedMode": { "default": false, "deprecated": true, "description": "Deprecated compatibility field; Producer compose ignores this value.", "type": "boolean" }, "bpm": { "description": "Optional BPM hint", "maximum": 999, "minimum": 1, "type": "number" }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "conversationId": { "type": "string", "description": "Existing Producer conversation identifier to continue." }, "currentSongId": { "description": "Optional current song id used for queue/context continuity", "type": "string" }, "imageId": { "description": "Optional cover image id", "type": "string" }, "imagePrompt": { "description": "Optional prompt for generating a cover image", "maxLength": 1000, "type": "string" }, "instrumental": { "default": false, "description": "Whether to force instrumental generation", "type": "boolean" }, "length": { "description": "Optional length hint in seconds. Lyria 3.5 requires 60-180 seconds; Lyria 3 Pro accepts shorter values.", "maximum": 180, "minimum": 1, "type": "number" }, "lyrics": { "description": "Optional lyrics text for compose generation. If omitted while instrumental=false, OmnAPI auto-generates lyrics before compose.", "maxLength": 3000, "type": "string" }, "lyricsId": { "description": "Optional existing lyrics id", "type": "string" }, "model": { "enum": [ "Lyria 3.5", "Lyria 3 Pro", "Lyria 3 preview" ], "type": "string", "description": "Model identifier accepted by this schema variant." }, "seed": { "description": "Optional seed value", "minimum": 0, "type": "number" }, "soundPrompt": { "description": "Sound prompt for music generation", "maxLength": 500, "type": "string" }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "soundPrompt" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "advancedMode": { "default": false, "deprecated": true, "description": "Deprecated compatibility field; Producer compose ignores this value.", "type": "boolean" }, "bpm": { "description": "Optional BPM hint", "maximum": 999, "minimum": 1, "type": "number" }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "conversationId": { "type": "string", "description": "Existing Producer conversation identifier to continue." }, "currentSongId": { "description": "Optional current song id used for queue/context continuity", "type": "string" }, "imageId": { "description": "Optional cover image id", "type": "string" }, "imagePrompt": { "description": "Optional prompt for generating a cover image", "maxLength": 1000, "type": "string" }, "instrumental": { "default": false, "description": "Whether to force instrumental generation", "type": "boolean" }, "length": { "description": "Optional length hint in seconds. Lyria 3.5 requires 60-180 seconds; Lyria 3 Pro accepts shorter values.", "maximum": 180, "minimum": 1, "type": "number" }, "lyrics": { "description": "Optional lyrics text for compose generation. If omitted while instrumental=false, OmnAPI auto-generates lyrics before compose.", "maxLength": 3000, "type": "string" }, "lyricsId": { "description": "Optional existing lyrics id", "type": "string" }, "model": { "enum": [ "Lyria 3.5", "Lyria 3 Pro", "Lyria 3 preview" ], "type": "string", "description": "Model identifier accepted by this schema variant." }, "seed": { "description": "Optional seed value", "minimum": 0, "type": "number" }, "soundPrompt": { "description": "Sound prompt for music generation", "maxLength": 500, "type": "string" }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "soundPrompt" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "advancedMode": { "default": false, "deprecated": true, "description": "Deprecated compatibility field; Producer compose ignores this value.", "type": "boolean" }, "bpm": { "description": "Optional BPM hint", "maximum": 999, "minimum": 1, "type": "number" }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "conversationId": { "type": "string", "description": "Existing Producer conversation identifier to continue." }, "currentSongId": { "description": "Optional current song id used for queue/context continuity", "type": "string" }, "imageId": { "description": "Optional cover image id", "type": "string" }, "imagePrompt": { "description": "Optional prompt for generating a cover image", "maxLength": 1000, "type": "string" }, "instrumental": { "default": false, "description": "Whether to force instrumental generation", "type": "boolean" }, "length": { "description": "Optional length hint in seconds. Lyria 3.5 requires 60-180 seconds; Lyria 3 Pro accepts shorter values.", "maximum": 180, "minimum": 1, "type": "number" }, "lyrics": { "description": "Optional lyrics text for compose generation. If omitted while instrumental=false, OmnAPI auto-generates lyrics before compose.", "maxLength": 3000, "type": "string" }, "lyricsId": { "description": "Optional existing lyrics id", "type": "string" }, "model": { "enum": [ "Lyria 3.5", "Lyria 3 Pro", "Lyria 3 preview" ], "type": "string", "description": "Model identifier accepted by this schema variant." }, "seed": { "description": "Optional seed value", "minimum": 0, "type": "number" }, "soundPrompt": { "description": "Sound prompt for music generation", "maxLength": 500, "type": "string" }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "soundPrompt" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsRequired": { "description": "Exact credits deducted to start the task", "minimum": 0, "type": "number" }, "estimatedCompletionTime": { "anyOf": [ { "anyOf": [ { "description": "Estimated completion time", "type": "Date" }, { "format": "date-time", "type": "string" }, { "format": "date", "type": "string" }, { "type": "number" } ], "description": "Estimated completion time" }, { "type": "null" } ], "nullable": true }, "links": { "additionalProperties": false, "properties": { "final": { "anyOf": [ { "description": "Final downloadable resource URL when available", "type": "string" }, { "type": "null" } ], "nullable": true }, "resource": { "anyOf": [ { "description": "Product resource URL when the product has a dedicated view endpoint", "type": "string" }, { "type": "null" } ], "nullable": true }, "stream": { "description": "Task SSE stream URL for the created task", "type": "string" }, "task": { "description": "Task polling URL for the created task", "type": "string" } }, "required": [ "task", "stream", "resource", "final" ], "type": "object" }, "pricing": { "additionalProperties": false, "properties": { "adjustmentCredits": { "description": "chargedCredits - baseCredits", "type": "number" }, "baseCredits": { "description": "Standard quoted credits before customer pricing adjustment", "type": "number" }, "billingIncrementCredits": { "description": "Smallest customer charge increment", "minimum": 0.0001, "type": "number" }, "calculatedCredits": { "description": "Precise whole-order subtotal before settlement rounding", "type": "number" }, "chargedCredits": { "description": "Credits charged for this create request", "minimum": 0, "type": "number" }, "quoteVersion": { "description": "Pricing quote version stored with the task", "type": "number" }, "settlementPolicyVersion": { "description": "Versioned customer settlement policy", "type": "string" }, "settlementRoundingCredits": { "description": "Whole-order rounding adjustment added at settlement", "minimum": 0, "type": "number" }, "source": { "enum": [ "standard", "customer_rule" ], "type": "string" } }, "required": [ "baseCredits", "chargedCredits", "adjustmentCredits", "source", "quoteVersion" ], "type": "object" }, "product": { "additionalProperties": false, "properties": { "autoFinalize": { "description": "Whether the product should finalize automatically", "type": "boolean" }, "deliveryStatus": { "anyOf": [ { "description": "Product-level delivery status when applicable", "type": "string" }, { "type": "null" } ], "nullable": true }, "featureCode": { "description": "Resolved feature code", "type": "string" }, "modelCode": { "description": "Resolved model code", "type": "string" }, "providerCode": { "description": "Resolved provider code", "type": "string" }, "resourceId": { "anyOf": [ { "description": "Product resource id when created synchronously", "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "description": "Product family for this task, e.g. suno, producer, mv", "type": "string" } }, "required": [ "type", "providerCode", "modelCode", "featureCode", "resourceId" ], "type": "object" }, "requestId": { "anyOf": [ { "description": "Request id echoed from X-Request-Id or generated by API", "type": "string" }, { "type": "null" } ], "nullable": true }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "description": "Task unique identifier", "type": "string" }, "warningCodes": { "items": { "description": "Non-fatal request warnings", "type": "string" }, "type": "array" } }, "required": [ "taskId", "status", "creditsRequired", "requestId", "links", "pricing", "product", "warningCodes" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "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." }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "Generate Music (Compose)", "tags": [ "Producer" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/producer/generate/music/modify": { "post": { "description": "Queue a Producer edit. Current deterministic modes (extend, cover, replace) use Recipe + audio__render_edit; legacy swap modes use conversation interpretation.", "operationId": "postApiV1ProducerGenerateMusicModify", "parameters": [ { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "clipId": { "description": "Source clip id to modify", "type": "string" }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "conversationId": { "description": "Optional existing conversation id to reuse", "type": "string" }, "cropEndAt": { "deprecated": true, "description": "Deprecated alias for extendFromSeconds", "minimum": 0, "type": "number" }, "currentSongId": { "description": "Optional current song id for client_context; defaults to clipId", "type": "string" }, "extendFromSeconds": { "description": "Source timestamp where extension begins", "minimum": 0, "type": "number" }, "extendSeconds": { "default": 60, "description": "Seconds generated by ExtendSection", "exclusiveMinimum": 0, "maximum": 180, "type": "number" }, "imageId": { "description": "Optional output cover image id", "type": "string" }, "lyrics": { "description": "New lyrics (useful for cover / swap_vocals)", "maxLength": 3000, "type": "string" }, "lyricsId": { "description": "Optional lyrics id paired with lyrics when using conversation-based modify flows", "type": "string" }, "modifyMode": { "enum": [ "task", "conversation" ], "type": "string", "description": "Producer modification transport mode." }, "prompt": { "description": "Additional modification instructions", "maxLength": 1000, "type": "string" }, "regions": { "description": "Ordered, non-overlapping regions for ReplaceSection", "items": { "additionalProperties": false, "properties": { "end": { "description": "Region end timestamp in seconds", "exclusiveMinimum": 0, "type": "number" }, "start": { "description": "Region start timestamp in seconds", "minimum": 0, "type": "number" } }, "required": [ "start", "end" ], "type": "object" }, "minItems": 1, "type": "array" }, "replaceEndAt": { "deprecated": true, "description": "Deprecated single-region alias for regions[].end", "minimum": 0, "type": "number" }, "replaceStartAt": { "deprecated": true, "description": "Deprecated single-region alias for regions[].start", "minimum": 0, "type": "number" }, "seed": { "description": "Optional deterministic seed for the modification", "minimum": 0, "type": "number" }, "soundPrompt": { "description": "New sound prompt (useful for swap_sound)", "maxLength": 500, "type": "string" }, "strength": { "default": 0.5, "description": "Cover similarity strength (0-1)", "maximum": 1, "minimum": 0, "type": "number" }, "tags": { "description": "Style tags for the modified clip", "maxLength": 300, "type": "string" }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." }, "transform": { "enum": [ "extend", "cover", "replace", "inpaint", "swap_vocals", "swap_sound" ], "type": "string", "description": "Producer music modification operation." } }, "required": [ "clipId", "transform" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "clipId": { "description": "Source clip id to modify", "type": "string" }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "conversationId": { "description": "Optional existing conversation id to reuse", "type": "string" }, "cropEndAt": { "deprecated": true, "description": "Deprecated alias for extendFromSeconds", "minimum": 0, "type": "number" }, "currentSongId": { "description": "Optional current song id for client_context; defaults to clipId", "type": "string" }, "extendFromSeconds": { "description": "Source timestamp where extension begins", "minimum": 0, "type": "number" }, "extendSeconds": { "default": 60, "description": "Seconds generated by ExtendSection", "exclusiveMinimum": 0, "maximum": 180, "type": "number" }, "imageId": { "description": "Optional output cover image id", "type": "string" }, "lyrics": { "description": "New lyrics (useful for cover / swap_vocals)", "maxLength": 3000, "type": "string" }, "lyricsId": { "description": "Optional lyrics id paired with lyrics when using conversation-based modify flows", "type": "string" }, "modifyMode": { "enum": [ "task", "conversation" ], "type": "string", "description": "Producer modification transport mode." }, "prompt": { "description": "Additional modification instructions", "maxLength": 1000, "type": "string" }, "regions": { "description": "Ordered, non-overlapping regions for ReplaceSection", "items": { "additionalProperties": false, "properties": { "end": { "description": "Region end timestamp in seconds", "exclusiveMinimum": 0, "type": "number" }, "start": { "description": "Region start timestamp in seconds", "minimum": 0, "type": "number" } }, "required": [ "start", "end" ], "type": "object" }, "minItems": 1, "type": "array" }, "replaceEndAt": { "deprecated": true, "description": "Deprecated single-region alias for regions[].end", "minimum": 0, "type": "number" }, "replaceStartAt": { "deprecated": true, "description": "Deprecated single-region alias for regions[].start", "minimum": 0, "type": "number" }, "seed": { "description": "Optional deterministic seed for the modification", "minimum": 0, "type": "number" }, "soundPrompt": { "description": "New sound prompt (useful for swap_sound)", "maxLength": 500, "type": "string" }, "strength": { "default": 0.5, "description": "Cover similarity strength (0-1)", "maximum": 1, "minimum": 0, "type": "number" }, "tags": { "description": "Style tags for the modified clip", "maxLength": 300, "type": "string" }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." }, "transform": { "enum": [ "extend", "cover", "replace", "inpaint", "swap_vocals", "swap_sound" ], "type": "string", "description": "Producer music modification operation." } }, "required": [ "clipId", "transform" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "clipId": { "description": "Source clip id to modify", "type": "string" }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "conversationId": { "description": "Optional existing conversation id to reuse", "type": "string" }, "cropEndAt": { "deprecated": true, "description": "Deprecated alias for extendFromSeconds", "minimum": 0, "type": "number" }, "currentSongId": { "description": "Optional current song id for client_context; defaults to clipId", "type": "string" }, "extendFromSeconds": { "description": "Source timestamp where extension begins", "minimum": 0, "type": "number" }, "extendSeconds": { "default": 60, "description": "Seconds generated by ExtendSection", "exclusiveMinimum": 0, "maximum": 180, "type": "number" }, "imageId": { "description": "Optional output cover image id", "type": "string" }, "lyrics": { "description": "New lyrics (useful for cover / swap_vocals)", "maxLength": 3000, "type": "string" }, "lyricsId": { "description": "Optional lyrics id paired with lyrics when using conversation-based modify flows", "type": "string" }, "modifyMode": { "enum": [ "task", "conversation" ], "type": "string", "description": "Producer modification transport mode." }, "prompt": { "description": "Additional modification instructions", "maxLength": 1000, "type": "string" }, "regions": { "description": "Ordered, non-overlapping regions for ReplaceSection", "items": { "additionalProperties": false, "properties": { "end": { "description": "Region end timestamp in seconds", "exclusiveMinimum": 0, "type": "number" }, "start": { "description": "Region start timestamp in seconds", "minimum": 0, "type": "number" } }, "required": [ "start", "end" ], "type": "object" }, "minItems": 1, "type": "array" }, "replaceEndAt": { "deprecated": true, "description": "Deprecated single-region alias for regions[].end", "minimum": 0, "type": "number" }, "replaceStartAt": { "deprecated": true, "description": "Deprecated single-region alias for regions[].start", "minimum": 0, "type": "number" }, "seed": { "description": "Optional deterministic seed for the modification", "minimum": 0, "type": "number" }, "soundPrompt": { "description": "New sound prompt (useful for swap_sound)", "maxLength": 500, "type": "string" }, "strength": { "default": 0.5, "description": "Cover similarity strength (0-1)", "maximum": 1, "minimum": 0, "type": "number" }, "tags": { "description": "Style tags for the modified clip", "maxLength": 300, "type": "string" }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." }, "transform": { "enum": [ "extend", "cover", "replace", "inpaint", "swap_vocals", "swap_sound" ], "type": "string", "description": "Producer music modification operation." } }, "required": [ "clipId", "transform" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsRequired": { "description": "Exact credits deducted to start the task", "minimum": 0, "type": "number" }, "estimatedCompletionTime": { "anyOf": [ { "anyOf": [ { "description": "Estimated completion time", "type": "Date" }, { "format": "date-time", "type": "string" }, { "format": "date", "type": "string" }, { "type": "number" } ], "description": "Estimated completion time" }, { "type": "null" } ], "nullable": true }, "links": { "additionalProperties": false, "properties": { "final": { "anyOf": [ { "description": "Final downloadable resource URL when available", "type": "string" }, { "type": "null" } ], "nullable": true }, "resource": { "anyOf": [ { "description": "Product resource URL when the product has a dedicated view endpoint", "type": "string" }, { "type": "null" } ], "nullable": true }, "stream": { "description": "Task SSE stream URL for the created task", "type": "string" }, "task": { "description": "Task polling URL for the created task", "type": "string" } }, "required": [ "task", "stream", "resource", "final" ], "type": "object" }, "pricing": { "additionalProperties": false, "properties": { "adjustmentCredits": { "description": "chargedCredits - baseCredits", "type": "number" }, "baseCredits": { "description": "Standard quoted credits before customer pricing adjustment", "type": "number" }, "billingIncrementCredits": { "description": "Smallest customer charge increment", "minimum": 0.0001, "type": "number" }, "calculatedCredits": { "description": "Precise whole-order subtotal before settlement rounding", "type": "number" }, "chargedCredits": { "description": "Credits charged for this create request", "minimum": 0, "type": "number" }, "quoteVersion": { "description": "Pricing quote version stored with the task", "type": "number" }, "settlementPolicyVersion": { "description": "Versioned customer settlement policy", "type": "string" }, "settlementRoundingCredits": { "description": "Whole-order rounding adjustment added at settlement", "minimum": 0, "type": "number" }, "source": { "enum": [ "standard", "customer_rule" ], "type": "string" } }, "required": [ "baseCredits", "chargedCredits", "adjustmentCredits", "source", "quoteVersion" ], "type": "object" }, "product": { "additionalProperties": false, "properties": { "autoFinalize": { "description": "Whether the product should finalize automatically", "type": "boolean" }, "deliveryStatus": { "anyOf": [ { "description": "Product-level delivery status when applicable", "type": "string" }, { "type": "null" } ], "nullable": true }, "featureCode": { "description": "Resolved feature code", "type": "string" }, "modelCode": { "description": "Resolved model code", "type": "string" }, "providerCode": { "description": "Resolved provider code", "type": "string" }, "resourceId": { "anyOf": [ { "description": "Product resource id when created synchronously", "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "description": "Product family for this task, e.g. suno, producer, mv", "type": "string" } }, "required": [ "type", "providerCode", "modelCode", "featureCode", "resourceId" ], "type": "object" }, "requestId": { "anyOf": [ { "description": "Request id echoed from X-Request-Id or generated by API", "type": "string" }, { "type": "null" } ], "nullable": true }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "description": "Task unique identifier", "type": "string" }, "warningCodes": { "items": { "description": "Non-fatal request warnings", "type": "string" }, "type": "array" } }, "required": [ "taskId", "status", "creditsRequired", "requestId", "links", "pricing", "product", "warningCodes" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "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." }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "Generate Music (Modify)", "tags": [ "Producer" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/subtitles/": { "post": { "description": "Extract lyrics and aligned subtitle artifacts from a public audio URL.", "operationId": "postApiV1Subtitles", "parameters": [ { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "budget": { "additionalProperties": false, "properties": { "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." } }, "type": "object", "description": "Public price guard for this request." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "language": { "maxLength": 16, "minLength": 2, "type": "string", "description": "Requested or known language code/name." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "extract", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "outputs": { "items": { "enum": [ "srt", "vtt", "lrc", "json" ], "type": "string" }, "maxItems": 4, "minItems": 1, "type": "array", "description": "Requested subtitle artifact formats." }, "source": { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "maximum": 600, "minimum": 1, "type": "number", "description": "Requested or known media duration in seconds." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object", "description": "Public source media or product reference." } }, "required": [ "source" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "budget": { "additionalProperties": false, "properties": { "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." } }, "type": "object", "description": "Public price guard for this request." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "language": { "maxLength": 16, "minLength": 2, "type": "string", "description": "Requested or known language code/name." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "extract", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "outputs": { "items": { "enum": [ "srt", "vtt", "lrc", "json" ], "type": "string" }, "maxItems": 4, "minItems": 1, "type": "array", "description": "Requested subtitle artifact formats." }, "source": { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "maximum": 600, "minimum": 1, "type": "number", "description": "Requested or known media duration in seconds." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object", "description": "Public source media or product reference." } }, "required": [ "source" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "budget": { "additionalProperties": false, "properties": { "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." } }, "type": "object", "description": "Public price guard for this request." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "language": { "maxLength": 16, "minLength": 2, "type": "string", "description": "Requested or known language code/name." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "extract", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "outputs": { "items": { "enum": [ "srt", "vtt", "lrc", "json" ], "type": "string" }, "maxItems": 4, "minItems": 1, "type": "array", "description": "Requested subtitle artifact formats." }, "source": { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "maximum": 600, "minimum": 1, "type": "number", "description": "Requested or known media duration in seconds." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object", "description": "Public source media or product reference." } }, "required": [ "source" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsRequired": { "type": "number" }, "pollUrl": { "type": "string" }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "type": "string" } }, "required": [ "taskId", "status", "creditsRequired", "pollUrl" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "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." }, "408": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 408" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 409" }, "413": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 413" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 502" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Create subtitle extraction task", "tags": [ "Subtitles" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/subtitles/quote": { "post": { "description": "Estimate credits and public price for audio-to-lyrics subtitle extraction.", "operationId": "postApiV1SubtitlesQuote", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "budget": { "additionalProperties": false, "properties": { "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." } }, "type": "object", "description": "Public price guard for this request." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "language": { "maxLength": 16, "minLength": 2, "type": "string", "description": "Requested or known language code/name." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "extract", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "outputs": { "items": { "enum": [ "srt", "vtt", "lrc", "json" ], "type": "string" }, "maxItems": 4, "minItems": 1, "type": "array", "description": "Requested subtitle artifact formats." }, "source": { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "maximum": 600, "minimum": 1, "type": "number", "description": "Requested or known media duration in seconds." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object", "description": "Public source media or product reference." } }, "required": [ "source" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "budget": { "additionalProperties": false, "properties": { "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." } }, "type": "object", "description": "Public price guard for this request." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "language": { "maxLength": 16, "minLength": 2, "type": "string", "description": "Requested or known language code/name." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "extract", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "outputs": { "items": { "enum": [ "srt", "vtt", "lrc", "json" ], "type": "string" }, "maxItems": 4, "minItems": 1, "type": "array", "description": "Requested subtitle artifact formats." }, "source": { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "maximum": 600, "minimum": 1, "type": "number", "description": "Requested or known media duration in seconds." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object", "description": "Public source media or product reference." } }, "required": [ "source" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "budget": { "additionalProperties": false, "properties": { "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." } }, "type": "object", "description": "Public price guard for this request." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "language": { "maxLength": 16, "minLength": 2, "type": "string", "description": "Requested or known language code/name." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "extract", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "outputs": { "items": { "enum": [ "srt", "vtt", "lrc", "json" ], "type": "string" }, "maxItems": 4, "minItems": 1, "type": "array", "description": "Requested subtitle artifact formats." }, "source": { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "maximum": 600, "minimum": 1, "type": "number", "description": "Requested or known media duration in seconds." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object", "description": "Public source media or product reference." } }, "required": [ "source" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "credits": { "type": "number" }, "durationSec": { "type": "number" }, "estimatedUsd": { "type": "number" }, "maxCostUsdPerMin": { "type": "number" }, "publicUsdPerMin": { "type": "number" } }, "required": [ "credits", "durationSec", "estimatedUsd", "maxCostUsdPerMin", "publicUsdPerMin" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Forbidden: the API key lacks the required scope or its IP policy rejects this request." }, "408": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 408" }, "413": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 413" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 502" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Quote subtitle extraction", "tags": [ "Subtitles" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/subtitles/{id}": { "get": { "description": "Get subtitle extraction task status and artifacts.", "operationId": "getApiV1SubtitlesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Resource identifier returned by the corresponding create operation." } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "artifacts": { "additionalProperties": false, "properties": { "json": { "additionalProperties": false, "properties": { "expiresAt": { "type": "string" }, "retentionDays": { "type": "number" }, "url": { "type": "string" } }, "required": [ "url" ], "type": "object" }, "jsonUrl": { "type": "string" }, "lrc": { "additionalProperties": false, "properties": { "expiresAt": { "type": "string" }, "retentionDays": { "type": "number" }, "url": { "type": "string" } }, "required": [ "url" ], "type": "object" }, "lrcUrl": { "type": "string" }, "srt": { "additionalProperties": false, "properties": { "expiresAt": { "type": "string" }, "retentionDays": { "type": "number" }, "url": { "type": "string" } }, "required": [ "url" ], "type": "object" }, "srtUrl": { "type": "string" }, "vtt": { "additionalProperties": false, "properties": { "expiresAt": { "type": "string" }, "retentionDays": { "type": "number" }, "url": { "type": "string" } }, "required": [ "url" ], "type": "object" }, "vttUrl": { "type": "string" } }, "required": [ "srt", "json", "srtUrl", "jsonUrl" ], "type": "object" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "lyrics": { "type": "string" }, "progress": { "maximum": 100, "minimum": 0, "type": "number" }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "type": "string" }, "timeline": { "additionalProperties": false, "properties": { "lines": { "items": { "additionalProperties": false, "properties": { "endSec": { "type": "number" }, "section": { "type": "string" }, "startSec": { "type": "number" }, "text": { "type": "string" } }, "required": [ "text", "startSec", "endSec" ], "type": "object" }, "type": "array" }, "words": { "items": { "additionalProperties": false, "properties": { "endSec": { "type": "number" }, "startSec": { "type": "number" }, "text": { "type": "string" } }, "required": [ "text", "startSec", "endSec" ], "type": "object" }, "type": "array" } }, "required": [ "lines", "words" ], "type": "object" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "required": [ "taskId", "status", "progress" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "Get subtitle task", "tags": [ "Subtitles" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/suno/assets": { "get": { "description": "Tenant-owned new-policy deliveries remain discoverable independently of Task history. Historical permanent assets remain on their original access paths.", "operationId": "getApiV1SunoAssets", "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 64, "type": "string" }, "description": "Opaque pagination cursor returned as nextCursor; omit it on the first page." }, { "in": "query", "name": "limit", "required": false, "schema": { "anyOf": [ { "default": 0, "format": "numeric", "type": "string" }, { "default": 20, "maximum": 100, "minimum": 1, "type": "number" } ], "default": 20, "maximum": 100, "minimum": 1 }, "description": "Maximum number of items to return." } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "items": { "items": { "properties": { "byteLength": { "type": "string" }, "clipId": { "type": "string" }, "deliveredAt": { "format": "date-time", "type": "string" }, "format": { "type": "string" }, "id": { "type": "string" }, "policy": { "type": "string" }, "retainedUntil": { "format": "date-time", "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "clipId", "format", "byteLength", "deliveredAt", "retainedUntil", "status", "policy" ], "type": "object" }, "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "List retained Suno assets", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/suno/assets/{id}/download": { "get": { "description": "Returns a private URL valid for at most one hour and never beyond retention. Expired deliveries return 410; other users' assets return 404. Lyrics downloads are gzip-compressed JSON snapshots.", "operationId": "getApiV1SunoAssetsByIdDownload", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 64, "type": "string" }, "description": "Resource identifier returned by the corresponding create operation." } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "properties": { "byteLength": { "type": "string" }, "clipId": { "type": "string" }, "deliveredAt": { "format": "date-time", "type": "string" }, "format": { "type": "string" }, "id": { "type": "string" }, "policy": { "type": "string" }, "retainedUntil": { "format": "date-time", "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "clipId", "format", "byteLength", "deliveredAt", "retainedUntil", "status", "policy" ], "type": "object" }, { "properties": { "url": { "type": "string" }, "urlExpiresAt": { "format": "date-time", "type": "string" } }, "required": [ "url", "urlExpiresAt" ], "type": "object" } ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "410": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 410" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Get a retained Suno asset download", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/suno/availability": { "get": { "description": "Advisory delivery health for Suno operations, including whether advanced operations are currently available.", "operationId": "getApiV1SunoAvailability", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "checkedAt": { "format": "date-time", "type": "string" }, "checks": { "items": { "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "status": { "enum": [ "pass", "warn", "fail", "unknown" ], "type": "string" } }, "required": [ "name", "status", "message" ], "type": "object" }, "type": "array" }, "guidance": { "type": "string" }, "message": { "type": "string" }, "retryAfterSec": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "status": { "enum": [ "available", "degraded", "unavailable", "unknown" ], "type": "string" }, "subscriptionOperationsAvailable": { "description": "Whether advanced Suno operations are currently available.", "type": "boolean" } }, "required": [ "status", "checkedAt", "retryAfterSec", "message", "guidance", "subscriptionOperationsAvailable", "checks" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Forbidden: the API key lacks the required scope or its IP policy rejects this request." }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "Get Suno availability", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/suno/clips": { "get": { "description": "Free direct batch read with the same per-clip access projection as the detail endpoint. Preserves request order, reports definitively absent IDs in missingClipIds, and reserves errors for transient per-ID read failures. No Task is created and no credits are charged.", "operationId": "getApiV1SunoClips", "parameters": [ { "in": "query", "name": "clipIds", "required": true, "schema": { "description": "Comma-separated external Suno clip IDs (legacy `mid` values).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "errors": { "items": { "additionalProperties": false, "properties": { "clipId": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "clipId", "code", "message", "retryable" ], "type": "object" }, "type": "array" }, "items": { "items": { "additionalProperties": false, "properties": { "accessLevel": { "enum": [ "owned", "shared", "external" ], "type": "string" }, "audioUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "clipId": { "description": "Suno clip identifier (`mid`); do not substitute an OmnAPI resource identifier.", "type": "string" }, "createdAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "deliveryStatus": { "enum": [ "submitted", "queued", "streaming", "complete", "error" ], "type": "string" }, "duration": { "anyOf": [ { "description": "Clip duration in seconds. Missing eventually-consistent metadata is repaired on later reads.", "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "imageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "index": { "minimum": 0, "type": "number" }, "instrumental": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "nullable": true }, "majorModelVersion": { "anyOf": [ { "description": "Exact Suno major_model_version value reported for this clip, for example v4.5-all.", "type": "string" }, { "type": "null" } ], "nullable": true }, "model": { "anyOf": [ { "description": "Compatibility model label. Prefer modelCode, providerModelName and majorModelVersion for unambiguous integrations.", "type": "string" }, { "type": "null" } ], "nullable": true }, "modelCode": { "anyOf": [ { "description": "Canonical OmnAPI model code selected for an owned generation. Null when a clip is read directly from Suno without a local task.", "type": "string" }, { "type": "null" } ], "nullable": true }, "playable": { "type": "boolean" }, "playback": { "additionalProperties": false, "properties": { "delivery": { "enum": [ "none", "chunked", "progressive" ], "type": "string" }, "expiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "mimeType": { "anyOf": [ { "anyOf": [ { "const": "audio/mpeg", "type": "string" }, { "const": "audio/mp4", "type": "string" } ] }, { "type": "null" } ], "nullable": true }, "retryAfterMs": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "seekable": { "type": "boolean" }, "sessionCreateUrl": { "anyOf": [ { "deprecated": true, "description": "Deprecated compatibility field. New integrations should use playback.url directly; no separate playback-session request is needed.", "type": "string" }, { "type": "null" } ], "nullable": true }, "state": { "enum": [ "preparing", "live", "final", "error", "unavailable" ], "type": "string" }, "url": { "anyOf": [ { "description": "Current playback URL. Live Generation reads provide a temporary URL; final reads provide the completed audio URL. Resolve relative URLs against the API base URL and open them without an API key. A null value means to wait and query the Generation again. Treat the complete URL as private and do not construct or modify it.", "type": "string" }, { "type": "null" } ], "nullable": true } }, "required": [ "state", "url", "mimeType", "delivery", "seekable", "expiresAt", "retryAfterMs", "sessionCreateUrl" ], "type": "object" }, "prompt": { "anyOf": [ { "description": "Generation prompt for owned clips only. Shared and external clips always return null.", "type": "string" }, { "type": "null" } ], "nullable": true }, "providerModelName": { "anyOf": [ { "description": "Exact Suno model_name value reported for this clip, for example chirp-hawk.", "type": "string" }, { "type": "null" } ], "nullable": true }, "role": { "enum": [ "candidate", "final" ], "type": "string" }, "tags": { "anyOf": [ { "description": "Public style tags for owned and shared clips. Null for external clips or before metadata propagation completes.", "type": "string" }, { "type": "null" } ], "nullable": true }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "updatedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "videoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true } }, "required": [ "clipId", "accessLevel", "index", "role", "deliveryStatus", "title", "tags", "prompt", "model", "modelCode", "providerModelName", "majorModelVersion", "instrumental", "audioUrl", "imageUrl", "videoUrl", "playable", "playback", "duration", "errorCode", "errorMessage", "createdAt", "updatedAt" ], "type": "object" }, "type": "array" }, "missingClipIds": { "items": { "type": "string" }, "type": "array" } }, "required": [ "items", "missingClipIds", "errors" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Forbidden: the API key lacks the required scope or its IP policy rejects this request." }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Query multiple clips", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/suno/clips/{clipId}": { "get": { "description": "Free direct resource read. `clipId` is the external Suno ID (legacy `mid`), never a TaskResult database ID. `accessLevel` controls field projection only: owned clips return the full contract, shared clips are public or remixable, and other readable external clips return minimal media fields. It does not grant derive or export permission. No Task is created or charged.", "operationId": "getApiV1SunoClipsByClipId", "parameters": [ { "in": "path", "name": "clipId", "required": true, "schema": { "type": "string" }, "description": "Suno clip identifier returned by a Generation or clip read." } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "accessLevel": { "enum": [ "owned", "shared", "external" ], "type": "string" }, "audioUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "clipId": { "description": "Suno clip identifier (`mid`); do not substitute an OmnAPI resource identifier.", "type": "string" }, "createdAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "deliveryStatus": { "enum": [ "submitted", "queued", "streaming", "complete", "error" ], "type": "string" }, "duration": { "anyOf": [ { "description": "Clip duration in seconds. Missing eventually-consistent metadata is repaired on later reads.", "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "imageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "index": { "minimum": 0, "type": "number" }, "instrumental": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "nullable": true }, "majorModelVersion": { "anyOf": [ { "description": "Exact Suno major_model_version value reported for this clip, for example v4.5-all.", "type": "string" }, { "type": "null" } ], "nullable": true }, "model": { "anyOf": [ { "description": "Compatibility model label. Prefer modelCode, providerModelName and majorModelVersion for unambiguous integrations.", "type": "string" }, { "type": "null" } ], "nullable": true }, "modelCode": { "anyOf": [ { "description": "Canonical OmnAPI model code selected for an owned generation. Null when a clip is read directly from Suno without a local task.", "type": "string" }, { "type": "null" } ], "nullable": true }, "playable": { "type": "boolean" }, "playback": { "additionalProperties": false, "properties": { "delivery": { "enum": [ "none", "chunked", "progressive" ], "type": "string" }, "expiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "mimeType": { "anyOf": [ { "anyOf": [ { "const": "audio/mpeg", "type": "string" }, { "const": "audio/mp4", "type": "string" } ] }, { "type": "null" } ], "nullable": true }, "retryAfterMs": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "seekable": { "type": "boolean" }, "sessionCreateUrl": { "anyOf": [ { "deprecated": true, "description": "Deprecated compatibility field. New integrations should use playback.url directly; no separate playback-session request is needed.", "type": "string" }, { "type": "null" } ], "nullable": true }, "state": { "enum": [ "preparing", "live", "final", "error", "unavailable" ], "type": "string" }, "url": { "anyOf": [ { "description": "Current playback URL. Live Generation reads provide a temporary URL; final reads provide the completed audio URL. Resolve relative URLs against the API base URL and open them without an API key. A null value means to wait and query the Generation again. Treat the complete URL as private and do not construct or modify it.", "type": "string" }, { "type": "null" } ], "nullable": true } }, "required": [ "state", "url", "mimeType", "delivery", "seekable", "expiresAt", "retryAfterMs", "sessionCreateUrl" ], "type": "object" }, "prompt": { "anyOf": [ { "description": "Generation prompt for owned clips only. Shared and external clips always return null.", "type": "string" }, { "type": "null" } ], "nullable": true }, "providerModelName": { "anyOf": [ { "description": "Exact Suno model_name value reported for this clip, for example chirp-hawk.", "type": "string" }, { "type": "null" } ], "nullable": true }, "role": { "enum": [ "candidate", "final" ], "type": "string" }, "tags": { "anyOf": [ { "description": "Public style tags for owned and shared clips. Null for external clips or before metadata propagation completes.", "type": "string" }, { "type": "null" } ], "nullable": true }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "updatedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "videoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true } }, "required": [ "clipId", "accessLevel", "index", "role", "deliveryStatus", "title", "tags", "prompt", "model", "modelCode", "providerModelName", "majorModelVersion", "instrumental", "audioUrl", "imageUrl", "videoUrl", "playable", "playback", "duration", "errorCode", "errorMessage", "createdAt", "updatedAt" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Forbidden: the API key lacks the required scope or its IP policy rejects this request." }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Get clip detail", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/suno/clips/{clipId}/audio-analysis": { "get": { "description": "Aggregates Suno downbeats, musical-key and waveform-mipmap analysis. Short sync-wait; returns 202 with taskId on timeout.", "operationId": "getApiV1SunoClipsByClipIdAudio_analysis", "parameters": [ { "in": "path", "name": "clipId", "required": true, "schema": { "type": "string" }, "description": "Suno clip identifier returned by a Generation or clip read." } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsCharged": { "anyOf": [ { "description": "Exact credits actually charged", "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "creditsRequired": { "description": "Exact credits deducted to start the task", "minimum": 0, "type": "number" }, "errorCode": { "anyOf": [ { "description": "Error code if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "errorMessage": { "anyOf": [ { "description": "Error message if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "outputResults": { "anyOf": [ { "additionalProperties": false, "properties": { "clipId": { "type": "string" }, "downbeats": { "patternProperties": { "^(.*)$": {} }, "type": "object" }, "key": { "patternProperties": { "^(.*)$": {} }, "type": "object" }, "waveform": { "patternProperties": { "^(.*)$": {} }, "type": "object" } }, "required": [ "clipId", "downbeats", "key", "waveform" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "pollUrl": { "anyOf": [ { "description": "Set only when the synchronous wait timed out (HTTP 202, status=PROCESSING). The task is still running — poll this URL for the final result. Null/absent on terminal responses.", "type": "string" }, { "type": "null" } ], "nullable": true }, "processingDuration": { "anyOf": [ { "description": "Processing duration in milliseconds", "type": "number" }, { "type": "null" } ], "nullable": true }, "processingDurationText": { "anyOf": [ { "description": "Human-readable processing duration, e.g. 16.2s", "type": "string" }, { "type": "null" } ], "nullable": true }, "resources": { "description": "Standardized resources produced by the task", "items": { "description": "A consumable resource produced by the task.", "properties": { "assetId": { "description": "Stable OmnAPI-owned asset id when available.", "type": "string" }, "assetStatus": { "enum": [ "READY", "EXPIRED", "DELETING", "DELETED" ], "type": "string" }, "byteLength": { "anyOf": [ { "description": "Resource size in bytes.", "type": "number" }, { "type": "null" } ], "nullable": true }, "content": { "anyOf": [ { "description": "Inline text content (e.g. lyrics).", "type": "string" }, { "type": "null" } ], "nullable": true }, "contentType": { "anyOf": [ { "description": "Resource content type.", "type": "string" }, { "type": "null" } ], "nullable": true }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "durationSec": { "anyOf": [ { "description": "Resource duration in seconds.", "type": "number" }, { "type": "null" } ], "nullable": true }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "id": { "description": "Stable resource id (OmnAPI resource id).", "type": "string" }, "index": { "description": "Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.", "minimum": 0, "type": "number" }, "metadata": { "anyOf": [ { "patternProperties": { "^(.*)$": {} }, "type": "object" }, { "type": "null" } ], "nullable": true }, "retainedUntil": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "role": { "enum": [ "candidate", "final", "stem", "fallback", "output" ], "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "enum": [ "MUSIC", "IMAGE", "VIDEO", "AUDIO", "TEXT", "METADATA" ], "type": "string" }, "url": { "anyOf": [ { "description": "Presigned/public URL.", "type": "string" }, { "type": "null" } ], "nullable": true }, "urlExpiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true } }, "required": [ "id", "index", "role", "type" ], "type": "object" }, "type": "array" }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "description": "Task unique identifier", "type": "string" } }, "required": [ "taskId", "status", "creditsRequired", "creditsCharged", "outputResults", "errorCode", "errorMessage", "processingDuration", "processingDurationText" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsCharged": { "anyOf": [ { "description": "Exact credits actually charged", "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "creditsRequired": { "description": "Exact credits deducted to start the task", "minimum": 0, "type": "number" }, "errorCode": { "anyOf": [ { "description": "Error code if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "errorMessage": { "anyOf": [ { "description": "Error message if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "outputResults": { "anyOf": [ { "additionalProperties": false, "properties": { "clipId": { "type": "string" }, "downbeats": { "patternProperties": { "^(.*)$": {} }, "type": "object" }, "key": { "patternProperties": { "^(.*)$": {} }, "type": "object" }, "waveform": { "patternProperties": { "^(.*)$": {} }, "type": "object" } }, "required": [ "clipId", "downbeats", "key", "waveform" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "pollUrl": { "anyOf": [ { "description": "Set only when the synchronous wait timed out (HTTP 202, status=PROCESSING). The task is still running — poll this URL for the final result. Null/absent on terminal responses.", "type": "string" }, { "type": "null" } ], "nullable": true }, "processingDuration": { "anyOf": [ { "description": "Processing duration in milliseconds", "type": "number" }, { "type": "null" } ], "nullable": true }, "processingDurationText": { "anyOf": [ { "description": "Human-readable processing duration, e.g. 16.2s", "type": "string" }, { "type": "null" } ], "nullable": true }, "resources": { "description": "Standardized resources produced by the task", "items": { "description": "A consumable resource produced by the task.", "properties": { "assetId": { "description": "Stable OmnAPI-owned asset id when available.", "type": "string" }, "assetStatus": { "enum": [ "READY", "EXPIRED", "DELETING", "DELETED" ], "type": "string" }, "byteLength": { "anyOf": [ { "description": "Resource size in bytes.", "type": "number" }, { "type": "null" } ], "nullable": true }, "content": { "anyOf": [ { "description": "Inline text content (e.g. lyrics).", "type": "string" }, { "type": "null" } ], "nullable": true }, "contentType": { "anyOf": [ { "description": "Resource content type.", "type": "string" }, { "type": "null" } ], "nullable": true }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "durationSec": { "anyOf": [ { "description": "Resource duration in seconds.", "type": "number" }, { "type": "null" } ], "nullable": true }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "id": { "description": "Stable resource id (OmnAPI resource id).", "type": "string" }, "index": { "description": "Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.", "minimum": 0, "type": "number" }, "metadata": { "anyOf": [ { "patternProperties": { "^(.*)$": {} }, "type": "object" }, { "type": "null" } ], "nullable": true }, "retainedUntil": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "role": { "enum": [ "candidate", "final", "stem", "fallback", "output" ], "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "enum": [ "MUSIC", "IMAGE", "VIDEO", "AUDIO", "TEXT", "METADATA" ], "type": "string" }, "url": { "anyOf": [ { "description": "Presigned/public URL.", "type": "string" }, { "type": "null" } ], "nullable": true }, "urlExpiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true } }, "required": [ "id", "index", "role", "type" ], "type": "object" }, "type": "array" }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "description": "Task unique identifier", "type": "string" } }, "required": [ "taskId", "status", "creditsRequired", "creditsCharged", "outputResults", "errorCode", "errorMessage", "processingDuration", "processingDurationText" ], "type": "object" } } }, "description": "Response for status 202", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "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." }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 422" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Get clip audio analysis", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/suno/clips/{clipId}/derive": { "post": { "description": "Extend or cover an existing Suno clip. Extend includes automatic Concat finalization in the same task and charge; use the resource with role=final as the complete song. There is no public Concat endpoint.", "operationId": "postApiV1SunoClipsByClipIdDerive", "parameters": [ { "in": "path", "name": "clipId", "required": true, "schema": { "description": "Concrete source clip/result ID for the selected candidate; task IDs are not accepted", "type": "string" } }, { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } }, { "description": "Set to respond-async to skip the acknowledgement wait and return the generation receipt immediately.", "in": "header", "name": "Prefer", "required": false, "schema": { "enum": [ "respond-async" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "action": { "enum": [ "extend", "cover" ], "type": "string", "description": "Operation action selected for this request." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "continueAt": { "description": "Timestamp in seconds to continue from. Values beyond the source duration are forwarded unchanged and Suno continues from the clip end.", "minimum": 0, "type": "number" }, "continuedAlignedPrompt": { "description": "Optional aligned continuation prompt for action=extend.", "maxLength": 5000, "type": "string" }, "controlSliders": { "properties": { "audio_weight": { "maximum": 1, "minimum": 0, "type": "number", "description": "Source-audio adherence weight from 0 to 1." }, "style_weight": { "maximum": 1, "minimum": 0, "type": "number", "description": "Style adherence weight from 0 to 1." }, "weirdness_constraint": { "maximum": 1, "minimum": 0, "type": "number", "description": "Creative-variation constraint from 0 to 1." } }, "type": "object", "description": "Optional bounded generation-control weights." }, "isInstrumental": { "type": "boolean", "description": "Optional instrumental intent for the derived result." }, "isRemix": { "type": "boolean", "description": "Optional remix intent for the derived result." }, "model": { "enum": [ "chirp-hawk", "chirp-hawk-wild", "chirp-goose", "chirp-auk-turbo", "chirp-v4", "chirp-auk", "chirp-bluejay", "chirp-crow", "chirp-fenix" ], "type": "string", "description": "Model identifier accepted by this schema variant." }, "negativeTags": { "maxLength": 1000, "type": "string", "description": "Negative music-style tags or exclusions." }, "prompt": { "maxLength": 5000, "type": "string", "description": "Primary creative or operation instruction." }, "tags": { "maxLength": 1000, "type": "string", "description": "Style tags or caller labels, as defined by this schema." }, "title": { "maxLength": 100, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "action" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "action": { "enum": [ "extend", "cover" ], "type": "string", "description": "Operation action selected for this request." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "continueAt": { "description": "Timestamp in seconds to continue from. Values beyond the source duration are forwarded unchanged and Suno continues from the clip end.", "minimum": 0, "type": "number" }, "continuedAlignedPrompt": { "description": "Optional aligned continuation prompt for action=extend.", "maxLength": 5000, "type": "string" }, "controlSliders": { "properties": { "audio_weight": { "maximum": 1, "minimum": 0, "type": "number", "description": "Source-audio adherence weight from 0 to 1." }, "style_weight": { "maximum": 1, "minimum": 0, "type": "number", "description": "Style adherence weight from 0 to 1." }, "weirdness_constraint": { "maximum": 1, "minimum": 0, "type": "number", "description": "Creative-variation constraint from 0 to 1." } }, "type": "object", "description": "Optional bounded generation-control weights." }, "isInstrumental": { "type": "boolean", "description": "Optional instrumental intent for the derived result." }, "isRemix": { "type": "boolean", "description": "Optional remix intent for the derived result." }, "model": { "enum": [ "chirp-hawk", "chirp-hawk-wild", "chirp-goose", "chirp-auk-turbo", "chirp-v4", "chirp-auk", "chirp-bluejay", "chirp-crow", "chirp-fenix" ], "type": "string", "description": "Model identifier accepted by this schema variant." }, "negativeTags": { "maxLength": 1000, "type": "string", "description": "Negative music-style tags or exclusions." }, "prompt": { "maxLength": 5000, "type": "string", "description": "Primary creative or operation instruction." }, "tags": { "maxLength": 1000, "type": "string", "description": "Style tags or caller labels, as defined by this schema." }, "title": { "maxLength": 100, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "action" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "action": { "enum": [ "extend", "cover" ], "type": "string", "description": "Operation action selected for this request." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "continueAt": { "description": "Timestamp in seconds to continue from. Values beyond the source duration are forwarded unchanged and Suno continues from the clip end.", "minimum": 0, "type": "number" }, "continuedAlignedPrompt": { "description": "Optional aligned continuation prompt for action=extend.", "maxLength": 5000, "type": "string" }, "controlSliders": { "properties": { "audio_weight": { "maximum": 1, "minimum": 0, "type": "number", "description": "Source-audio adherence weight from 0 to 1." }, "style_weight": { "maximum": 1, "minimum": 0, "type": "number", "description": "Style adherence weight from 0 to 1." }, "weirdness_constraint": { "maximum": 1, "minimum": 0, "type": "number", "description": "Creative-variation constraint from 0 to 1." } }, "type": "object", "description": "Optional bounded generation-control weights." }, "isInstrumental": { "type": "boolean", "description": "Optional instrumental intent for the derived result." }, "isRemix": { "type": "boolean", "description": "Optional remix intent for the derived result." }, "model": { "enum": [ "chirp-hawk", "chirp-hawk-wild", "chirp-goose", "chirp-auk-turbo", "chirp-v4", "chirp-auk", "chirp-bluejay", "chirp-crow", "chirp-fenix" ], "type": "string", "description": "Model identifier accepted by this schema variant." }, "negativeTags": { "maxLength": 1000, "type": "string", "description": "Negative music-style tags or exclusions." }, "prompt": { "maxLength": 5000, "type": "string", "description": "Primary creative or operation instruction." }, "tags": { "maxLength": 1000, "type": "string", "description": "Style tags or caller labels, as defined by this schema." }, "title": { "maxLength": 100, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "action" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "autoFinalize": { "type": "boolean" }, "clipIds": { "items": { "type": "string" }, "type": "array" }, "creditsRequired": { "minimum": 0, "type": "number" }, "deliveryStatus": { "anyOf": [ { "anyOf": [ { "const": "submitted", "type": "string" }, { "const": "queued", "type": "string" }, { "const": "streaming", "type": "string" }, { "const": "complete", "type": "string" }, { "const": "error", "type": "string" } ] }, { "type": "null" } ], "nullable": true }, "estimatedCompletionTime": { "anyOf": [ { "description": "Estimated completion time as an RFC 3339 string.", "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "finalUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "generationId": { "type": "string" }, "links": { "additionalProperties": false, "properties": { "final": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "resource": { "type": "string" }, "task": { "type": "string" } }, "required": [ "task", "resource", "final" ], "type": "object" }, "pollUrl": { "type": "string" }, "pricing": { "additionalProperties": false, "properties": { "adjustmentCredits": { "description": "chargedCredits - baseCredits", "type": "number" }, "baseCredits": { "description": "Standard quoted credits before customer pricing adjustment", "type": "number" }, "billingIncrementCredits": { "description": "Smallest customer charge increment", "minimum": 0.0001, "type": "number" }, "calculatedCredits": { "description": "Precise whole-order subtotal before settlement rounding", "type": "number" }, "chargedCredits": { "description": "Credits charged for this create request", "minimum": 0, "type": "number" }, "quoteVersion": { "description": "Pricing quote version stored with the task", "type": "number" }, "settlementPolicyVersion": { "description": "Versioned customer settlement policy", "type": "string" }, "settlementRoundingCredits": { "description": "Whole-order rounding adjustment added at settlement", "minimum": 0, "type": "number" }, "source": { "enum": [ "standard", "customer_rule" ], "type": "string" } }, "required": [ "baseCredits", "chargedCredits", "adjustmentCredits", "source", "quoteVersion" ], "type": "object" }, "product": { "additionalProperties": false, "properties": { "autoFinalize": { "type": "boolean" }, "deliveryStatus": { "anyOf": [ { "anyOf": [ { "const": "submitted", "type": "string" }, { "const": "queued", "type": "string" }, { "const": "streaming", "type": "string" }, { "const": "complete", "type": "string" }, { "const": "error", "type": "string" } ] }, { "type": "null" } ], "nullable": true }, "featureCode": { "type": "string" }, "modelCode": { "type": "string" }, "providerCode": { "const": "suno", "type": "string" }, "resourceId": { "type": "string" }, "type": { "const": "suno", "type": "string" } }, "required": [ "type", "providerCode", "modelCode", "featureCode", "resourceId", "deliveryStatus", "autoFinalize" ], "type": "object" }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "type": "string" }, "viewUrl": { "type": "string" }, "warningCodes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "taskId", "generationId", "status", "creditsRequired", "requestId", "links", "pricing", "product", "warningCodes", "clipIds", "pollUrl", "viewUrl", "finalUrl", "deliveryStatus", "autoFinalize" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "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." }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 422" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Derive a clip", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/suno/clips/{clipId}/export": { "post": { "description": "Export M4A (1 standard credit), MP3 (2), WAV (3), or separated tracks. WAV delivers the requested original clip. Twelve stems cost 140; Extract costs 56. Customer pricing applies to every operation. When managed storage is available, new ordinary audio has a 14-day retention period, extendable through explicitly enabled paid storage; WAV has fixed 180-day retention. Read retainedUntil and urlExpiresAt on returned resources. Refresh private URLs through task or asset reads; signed URLs last at most one hour and never outlive retention. Existing permanent delivery rights remain valid for the same customer. Never construct or assume permanent download URLs.", "operationId": "postApiV1SunoClipsByClipIdExport", "parameters": [ { "in": "path", "name": "clipId", "required": true, "schema": { "type": "string" }, "description": "Suno clip identifier returned by a Generation or clip read." }, { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "format": { "const": "wav", "type": "string", "description": "Requested output format discriminator." } }, "required": [ "format" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "format": { "const": "m4a", "description": "Export an M4A audio file. New managed deliveries have a 14-day retention period and renewable signed URLs; existing permanent delivery rights are preserved. Your account pricing applies to separately requested exports. Automatic audio delivery for a Suno creation task has no additional charge.", "type": "string" } }, "required": [ "format" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "format": { "const": "mp3", "description": "2-standard-credit MP3 export. Use the returned URL; do not construct download URLs. For managed assets, inspect retainedUntil and refresh expiring URLs through asset reads.", "type": "string" } }, "required": [ "format" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "format": { "const": "stems", "description": "Separated audio tracks.", "type": "string" }, "stemName": { "anyOf": [ { "const": "Lead Vocal", "type": "string" }, { "const": "Drum Kit", "type": "string" }, { "const": "Kick", "type": "string" }, { "const": "Snare", "type": "string" }, { "const": "Risers", "type": "string" }, { "const": "Bass", "type": "string" }, { "const": "Backing Vocals", "type": "string" }, { "const": "Piano", "type": "string" }, { "const": "Electric Guitar", "type": "string" }, { "const": "Percussion", "type": "string" }, { "const": "String Section", "type": "string" }, { "const": "Synth", "type": "string" }, { "const": "Acoustic Guitar", "type": "string" }, { "const": "Sound Effects", "type": "string" }, { "const": "Synth Pad", "type": "string" }, { "const": "Synth Bass", "type": "string" }, { "const": "Guitar", "type": "string" }, { "const": "Brass Section", "type": "string" }, { "const": "Organ", "type": "string" }, { "const": "Electronic Drum Kit", "type": "string" }, { "const": "Lead Electric Guitar", "type": "string" }, { "const": "Synth Keys", "type": "string" }, { "const": "Rhythm Electric Guitar", "type": "string" }, { "const": "Electric Piano", "type": "string" }, { "const": "Upright Bass", "type": "string" }, { "const": "Keyboards", "type": "string" }, { "const": "Distorted Electric Guitar", "type": "string" }, { "const": "Synth Strings", "type": "string" }, { "const": "Synth Lead", "type": "string" }, { "const": "Woodwinds", "type": "string" }, { "const": "Rhythm Acoustic Guitar", "type": "string" }, { "const": "Flute", "type": "string" }, { "const": "Harp", "type": "string" }, { "const": "Tambourine", "type": "string" }, { "const": "Trumpet", "type": "string" }, { "const": "Arpeggiator", "type": "string" }, { "const": "Accordion", "type": "string" }, { "const": "Fiddle", "type": "string" }, { "const": "Pedal Steel Guitar", "type": "string" }, { "const": "Synth Voice", "type": "string" }, { "const": "Violin", "type": "string" }, { "const": "Digital Piano", "type": "string" }, { "const": "Synth Brass", "type": "string" }, { "const": "Mandolin", "type": "string" }, { "const": "Choir", "type": "string" }, { "const": "Banjo", "type": "string" }, { "const": "Bells", "type": "string" }, { "const": "Clarinet", "type": "string" }, { "const": "Tenor Saxophone", "type": "string" }, { "const": "Trombone", "type": "string" }, { "const": "Shaker", "type": "string" }, { "const": "French Horn", "type": "string" }, { "const": "Glockenspiel", "type": "string" }, { "const": "Electric Bass", "type": "string" }, { "const": "Cello", "type": "string" }, { "const": "Timpani", "type": "string" }, { "const": "Harmonica", "type": "string" }, { "const": "Marimba", "type": "string" }, { "const": "Vibraphone", "type": "string" }, { "const": "Lap Steel Guitar", "type": "string" }, { "const": "Saxophone", "type": "string" }, { "const": "Orchestra", "type": "string" }, { "const": "Horns", "type": "string" }, { "const": "Cymbals", "type": "string" }, { "const": "Hand Clap", "type": "string" }, { "const": "Oboe", "type": "string" }, { "const": "Celesta", "type": "string" }, { "const": "Congas", "type": "string" }, { "const": "Drone", "type": "string" }, { "const": "Alto Saxophone", "type": "string" }, { "const": "Double Bass", "type": "string" }, { "const": "Ukulele", "type": "string" }, { "const": "Harpsichord", "type": "string" }, { "const": "Baritone Saxophone", "type": "string" }, { "const": "Xylophone", "type": "string" }, { "const": "Tuba", "type": "string" }, { "const": "Bass Guitar", "type": "string" }, { "const": "Whistle", "type": "string" }, { "const": "Lead Guitar", "type": "string" }, { "const": "Rhodes", "type": "string" }, { "const": "808", "type": "string" }, { "const": "Bongos", "type": "string" }, { "const": "Bassoon", "type": "string" }, { "const": "Cowbell", "type": "string" }, { "const": "Viola", "type": "string" }, { "const": "Sitar", "type": "string" }, { "const": "Steel Drums", "type": "string" }, { "const": "Piccolo", "type": "string" }, { "const": "Theremin", "type": "string" }, { "const": "Bagpipes", "type": "string" }, { "const": "Hi-Hat", "type": "string" }, { "const": "Music Box", "type": "string" }, { "const": "Melodica", "type": "string" }, { "const": "Tabla", "type": "string" }, { "const": "Koto", "type": "string" }, { "const": "Djembe", "type": "string" }, { "const": "Taiko", "type": "string" }, { "const": "Didgeridoo", "type": "string" } ], "description": "Required for stemsMode=extract. Use one exact canonical value from this enum." }, "stemsMode": { "anyOf": [ { "const": "twelve", "type": "string" }, { "const": "extract", "type": "string" } ], "description": "twelve = full split (140 standard credits, default); extract = isolate/remove one named stem (56 standard credits). Suno no longer supports two." } }, "required": [ "format" ], "type": "object" } ], "description": "Export a managed M4A (1 credit), MP3 (2 credits), WAV file, or managed separated stems from an existing clip." } }, "application/x-www-form-urlencoded": { "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "format": { "const": "wav", "type": "string", "description": "Requested output format discriminator." } }, "required": [ "format" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "format": { "const": "m4a", "description": "Export an M4A audio file. New managed deliveries have a 14-day retention period and renewable signed URLs; existing permanent delivery rights are preserved. Your account pricing applies to separately requested exports. Automatic audio delivery for a Suno creation task has no additional charge.", "type": "string" } }, "required": [ "format" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "format": { "const": "mp3", "description": "2-standard-credit MP3 export. Use the returned URL; do not construct download URLs. For managed assets, inspect retainedUntil and refresh expiring URLs through asset reads.", "type": "string" } }, "required": [ "format" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "format": { "const": "stems", "description": "Separated audio tracks.", "type": "string" }, "stemName": { "anyOf": [ { "const": "Lead Vocal", "type": "string" }, { "const": "Drum Kit", "type": "string" }, { "const": "Kick", "type": "string" }, { "const": "Snare", "type": "string" }, { "const": "Risers", "type": "string" }, { "const": "Bass", "type": "string" }, { "const": "Backing Vocals", "type": "string" }, { "const": "Piano", "type": "string" }, { "const": "Electric Guitar", "type": "string" }, { "const": "Percussion", "type": "string" }, { "const": "String Section", "type": "string" }, { "const": "Synth", "type": "string" }, { "const": "Acoustic Guitar", "type": "string" }, { "const": "Sound Effects", "type": "string" }, { "const": "Synth Pad", "type": "string" }, { "const": "Synth Bass", "type": "string" }, { "const": "Guitar", "type": "string" }, { "const": "Brass Section", "type": "string" }, { "const": "Organ", "type": "string" }, { "const": "Electronic Drum Kit", "type": "string" }, { "const": "Lead Electric Guitar", "type": "string" }, { "const": "Synth Keys", "type": "string" }, { "const": "Rhythm Electric Guitar", "type": "string" }, { "const": "Electric Piano", "type": "string" }, { "const": "Upright Bass", "type": "string" }, { "const": "Keyboards", "type": "string" }, { "const": "Distorted Electric Guitar", "type": "string" }, { "const": "Synth Strings", "type": "string" }, { "const": "Synth Lead", "type": "string" }, { "const": "Woodwinds", "type": "string" }, { "const": "Rhythm Acoustic Guitar", "type": "string" }, { "const": "Flute", "type": "string" }, { "const": "Harp", "type": "string" }, { "const": "Tambourine", "type": "string" }, { "const": "Trumpet", "type": "string" }, { "const": "Arpeggiator", "type": "string" }, { "const": "Accordion", "type": "string" }, { "const": "Fiddle", "type": "string" }, { "const": "Pedal Steel Guitar", "type": "string" }, { "const": "Synth Voice", "type": "string" }, { "const": "Violin", "type": "string" }, { "const": "Digital Piano", "type": "string" }, { "const": "Synth Brass", "type": "string" }, { "const": "Mandolin", "type": "string" }, { "const": "Choir", "type": "string" }, { "const": "Banjo", "type": "string" }, { "const": "Bells", "type": "string" }, { "const": "Clarinet", "type": "string" }, { "const": "Tenor Saxophone", "type": "string" }, { "const": "Trombone", "type": "string" }, { "const": "Shaker", "type": "string" }, { "const": "French Horn", "type": "string" }, { "const": "Glockenspiel", "type": "string" }, { "const": "Electric Bass", "type": "string" }, { "const": "Cello", "type": "string" }, { "const": "Timpani", "type": "string" }, { "const": "Harmonica", "type": "string" }, { "const": "Marimba", "type": "string" }, { "const": "Vibraphone", "type": "string" }, { "const": "Lap Steel Guitar", "type": "string" }, { "const": "Saxophone", "type": "string" }, { "const": "Orchestra", "type": "string" }, { "const": "Horns", "type": "string" }, { "const": "Cymbals", "type": "string" }, { "const": "Hand Clap", "type": "string" }, { "const": "Oboe", "type": "string" }, { "const": "Celesta", "type": "string" }, { "const": "Congas", "type": "string" }, { "const": "Drone", "type": "string" }, { "const": "Alto Saxophone", "type": "string" }, { "const": "Double Bass", "type": "string" }, { "const": "Ukulele", "type": "string" }, { "const": "Harpsichord", "type": "string" }, { "const": "Baritone Saxophone", "type": "string" }, { "const": "Xylophone", "type": "string" }, { "const": "Tuba", "type": "string" }, { "const": "Bass Guitar", "type": "string" }, { "const": "Whistle", "type": "string" }, { "const": "Lead Guitar", "type": "string" }, { "const": "Rhodes", "type": "string" }, { "const": "808", "type": "string" }, { "const": "Bongos", "type": "string" }, { "const": "Bassoon", "type": "string" }, { "const": "Cowbell", "type": "string" }, { "const": "Viola", "type": "string" }, { "const": "Sitar", "type": "string" }, { "const": "Steel Drums", "type": "string" }, { "const": "Piccolo", "type": "string" }, { "const": "Theremin", "type": "string" }, { "const": "Bagpipes", "type": "string" }, { "const": "Hi-Hat", "type": "string" }, { "const": "Music Box", "type": "string" }, { "const": "Melodica", "type": "string" }, { "const": "Tabla", "type": "string" }, { "const": "Koto", "type": "string" }, { "const": "Djembe", "type": "string" }, { "const": "Taiko", "type": "string" }, { "const": "Didgeridoo", "type": "string" } ], "description": "Required for stemsMode=extract. Use one exact canonical value from this enum." }, "stemsMode": { "anyOf": [ { "const": "twelve", "type": "string" }, { "const": "extract", "type": "string" } ], "description": "twelve = full split (140 standard credits, default); extract = isolate/remove one named stem (56 standard credits). Suno no longer supports two." } }, "required": [ "format" ], "type": "object" } ], "description": "Export a managed M4A (1 credit), MP3 (2 credits), WAV file, or managed separated stems from an existing clip." } }, "multipart/form-data": { "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "format": { "const": "wav", "type": "string", "description": "Requested output format discriminator." } }, "required": [ "format" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "format": { "const": "m4a", "description": "Export an M4A audio file. New managed deliveries have a 14-day retention period and renewable signed URLs; existing permanent delivery rights are preserved. Your account pricing applies to separately requested exports. Automatic audio delivery for a Suno creation task has no additional charge.", "type": "string" } }, "required": [ "format" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "format": { "const": "mp3", "description": "2-standard-credit MP3 export. Use the returned URL; do not construct download URLs. For managed assets, inspect retainedUntil and refresh expiring URLs through asset reads.", "type": "string" } }, "required": [ "format" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "format": { "const": "stems", "description": "Separated audio tracks.", "type": "string" }, "stemName": { "anyOf": [ { "const": "Lead Vocal", "type": "string" }, { "const": "Drum Kit", "type": "string" }, { "const": "Kick", "type": "string" }, { "const": "Snare", "type": "string" }, { "const": "Risers", "type": "string" }, { "const": "Bass", "type": "string" }, { "const": "Backing Vocals", "type": "string" }, { "const": "Piano", "type": "string" }, { "const": "Electric Guitar", "type": "string" }, { "const": "Percussion", "type": "string" }, { "const": "String Section", "type": "string" }, { "const": "Synth", "type": "string" }, { "const": "Acoustic Guitar", "type": "string" }, { "const": "Sound Effects", "type": "string" }, { "const": "Synth Pad", "type": "string" }, { "const": "Synth Bass", "type": "string" }, { "const": "Guitar", "type": "string" }, { "const": "Brass Section", "type": "string" }, { "const": "Organ", "type": "string" }, { "const": "Electronic Drum Kit", "type": "string" }, { "const": "Lead Electric Guitar", "type": "string" }, { "const": "Synth Keys", "type": "string" }, { "const": "Rhythm Electric Guitar", "type": "string" }, { "const": "Electric Piano", "type": "string" }, { "const": "Upright Bass", "type": "string" }, { "const": "Keyboards", "type": "string" }, { "const": "Distorted Electric Guitar", "type": "string" }, { "const": "Synth Strings", "type": "string" }, { "const": "Synth Lead", "type": "string" }, { "const": "Woodwinds", "type": "string" }, { "const": "Rhythm Acoustic Guitar", "type": "string" }, { "const": "Flute", "type": "string" }, { "const": "Harp", "type": "string" }, { "const": "Tambourine", "type": "string" }, { "const": "Trumpet", "type": "string" }, { "const": "Arpeggiator", "type": "string" }, { "const": "Accordion", "type": "string" }, { "const": "Fiddle", "type": "string" }, { "const": "Pedal Steel Guitar", "type": "string" }, { "const": "Synth Voice", "type": "string" }, { "const": "Violin", "type": "string" }, { "const": "Digital Piano", "type": "string" }, { "const": "Synth Brass", "type": "string" }, { "const": "Mandolin", "type": "string" }, { "const": "Choir", "type": "string" }, { "const": "Banjo", "type": "string" }, { "const": "Bells", "type": "string" }, { "const": "Clarinet", "type": "string" }, { "const": "Tenor Saxophone", "type": "string" }, { "const": "Trombone", "type": "string" }, { "const": "Shaker", "type": "string" }, { "const": "French Horn", "type": "string" }, { "const": "Glockenspiel", "type": "string" }, { "const": "Electric Bass", "type": "string" }, { "const": "Cello", "type": "string" }, { "const": "Timpani", "type": "string" }, { "const": "Harmonica", "type": "string" }, { "const": "Marimba", "type": "string" }, { "const": "Vibraphone", "type": "string" }, { "const": "Lap Steel Guitar", "type": "string" }, { "const": "Saxophone", "type": "string" }, { "const": "Orchestra", "type": "string" }, { "const": "Horns", "type": "string" }, { "const": "Cymbals", "type": "string" }, { "const": "Hand Clap", "type": "string" }, { "const": "Oboe", "type": "string" }, { "const": "Celesta", "type": "string" }, { "const": "Congas", "type": "string" }, { "const": "Drone", "type": "string" }, { "const": "Alto Saxophone", "type": "string" }, { "const": "Double Bass", "type": "string" }, { "const": "Ukulele", "type": "string" }, { "const": "Harpsichord", "type": "string" }, { "const": "Baritone Saxophone", "type": "string" }, { "const": "Xylophone", "type": "string" }, { "const": "Tuba", "type": "string" }, { "const": "Bass Guitar", "type": "string" }, { "const": "Whistle", "type": "string" }, { "const": "Lead Guitar", "type": "string" }, { "const": "Rhodes", "type": "string" }, { "const": "808", "type": "string" }, { "const": "Bongos", "type": "string" }, { "const": "Bassoon", "type": "string" }, { "const": "Cowbell", "type": "string" }, { "const": "Viola", "type": "string" }, { "const": "Sitar", "type": "string" }, { "const": "Steel Drums", "type": "string" }, { "const": "Piccolo", "type": "string" }, { "const": "Theremin", "type": "string" }, { "const": "Bagpipes", "type": "string" }, { "const": "Hi-Hat", "type": "string" }, { "const": "Music Box", "type": "string" }, { "const": "Melodica", "type": "string" }, { "const": "Tabla", "type": "string" }, { "const": "Koto", "type": "string" }, { "const": "Djembe", "type": "string" }, { "const": "Taiko", "type": "string" }, { "const": "Didgeridoo", "type": "string" } ], "description": "Required for stemsMode=extract. Use one exact canonical value from this enum." }, "stemsMode": { "anyOf": [ { "const": "twelve", "type": "string" }, { "const": "extract", "type": "string" } ], "description": "twelve = full split (140 standard credits, default); extract = isolate/remove one named stem (56 standard credits). Suno no longer supports two." } }, "required": [ "format" ], "type": "object" } ], "description": "Export a managed M4A (1 credit), MP3 (2 credits), WAV file, or managed separated stems from an existing clip." } } }, "description": "Export a managed M4A (1 credit), MP3 (2 credits), WAV file, or managed separated stems from an existing clip.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsRequired": { "minimum": 0, "type": "number" }, "estimatedCompletionTime": { "anyOf": [ { "description": "Estimated completion time as an RFC 3339 string.", "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "links": { "additionalProperties": false, "properties": { "final": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "resource": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "task": { "type": "string" } }, "required": [ "task", "resource", "final" ], "type": "object" }, "pricing": { "additionalProperties": false, "properties": { "adjustmentCredits": { "description": "chargedCredits - baseCredits", "type": "number" }, "baseCredits": { "description": "Standard quoted credits before customer pricing adjustment", "type": "number" }, "billingIncrementCredits": { "description": "Smallest customer charge increment", "minimum": 0.0001, "type": "number" }, "calculatedCredits": { "description": "Precise whole-order subtotal before settlement rounding", "type": "number" }, "chargedCredits": { "description": "Credits charged for this create request", "minimum": 0, "type": "number" }, "quoteVersion": { "description": "Pricing quote version stored with the task", "type": "number" }, "settlementPolicyVersion": { "description": "Versioned customer settlement policy", "type": "string" }, "settlementRoundingCredits": { "description": "Whole-order rounding adjustment added at settlement", "minimum": 0, "type": "number" }, "source": { "enum": [ "standard", "customer_rule" ], "type": "string" } }, "required": [ "baseCredits", "chargedCredits", "adjustmentCredits", "source", "quoteVersion" ], "type": "object" }, "product": { "additionalProperties": false, "properties": { "autoFinalize": { "description": "Whether the product should finalize automatically", "type": "boolean" }, "deliveryStatus": { "anyOf": [ { "description": "Product-level delivery status when applicable", "type": "string" }, { "type": "null" } ], "nullable": true }, "featureCode": { "description": "Resolved feature code", "type": "string" }, "modelCode": { "description": "Resolved model code", "type": "string" }, "providerCode": { "description": "Resolved provider code", "type": "string" }, "resourceId": { "anyOf": [ { "description": "Product resource id when created synchronously", "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "description": "Product family for this task, e.g. suno, producer, mv", "type": "string" } }, "required": [ "type", "providerCode", "modelCode", "featureCode", "resourceId" ], "type": "object" }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "type": "string" }, "warningCodes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "taskId", "status", "creditsRequired", "requestId", "links", "pricing", "product", "warningCodes" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "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." }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 422" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Export clip audio", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/suno/clips/{clipId}/timeline": { "get": { "description": "Word/line-level timestamps for a clip. Short sync-wait; returns 202 with taskId on timeout.", "operationId": "getApiV1SunoClipsByClipIdTimeline", "parameters": [ { "in": "path", "name": "clipId", "required": true, "schema": { "type": "string" }, "description": "Suno clip identifier returned by a Generation or clip read." } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsCharged": { "anyOf": [ { "description": "Exact credits actually charged", "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "creditsRequired": { "description": "Exact credits deducted to start the task", "minimum": 0, "type": "number" }, "errorCode": { "anyOf": [ { "description": "Error code if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "errorMessage": { "anyOf": [ { "description": "Error message if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "outputResults": { "anyOf": [ { "additionalProperties": false, "properties": { "clipId": { "type": "string" }, "lines": { "items": { "additionalProperties": false, "properties": { "end": { "minimum": 0, "type": "number" }, "section": { "type": "string" }, "start": { "minimum": 0, "type": "number" }, "text": { "type": "string" }, "words": { "items": { "additionalProperties": false, "properties": { "confidence": { "type": "number" }, "end": { "minimum": 0, "type": "number" }, "start": { "minimum": 0, "type": "number" }, "success": { "type": "boolean" }, "word": { "type": "string" } }, "required": [ "word", "start", "end" ], "type": "object" }, "type": "array" } }, "required": [ "text", "start", "end", "words" ], "type": "object" }, "type": "array" }, "waveform_data": { "items": { "type": "number" }, "type": "array" }, "words": { "items": { "additionalProperties": false, "properties": { "confidence": { "type": "number" }, "end": { "minimum": 0, "type": "number" }, "start": { "minimum": 0, "type": "number" }, "success": { "type": "boolean" }, "word": { "type": "string" } }, "required": [ "word", "start", "end" ], "type": "object" }, "type": "array" } }, "required": [ "clipId", "words", "lines", "waveform_data" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "pollUrl": { "anyOf": [ { "description": "Set only when the synchronous wait timed out (HTTP 202, status=PROCESSING). The task is still running — poll this URL for the final result. Null/absent on terminal responses.", "type": "string" }, { "type": "null" } ], "nullable": true }, "processingDuration": { "anyOf": [ { "description": "Processing duration in milliseconds", "type": "number" }, { "type": "null" } ], "nullable": true }, "processingDurationText": { "anyOf": [ { "description": "Human-readable processing duration, e.g. 16.2s", "type": "string" }, { "type": "null" } ], "nullable": true }, "resources": { "description": "Standardized resources produced by the task", "items": { "description": "A consumable resource produced by the task.", "properties": { "assetId": { "description": "Stable OmnAPI-owned asset id when available.", "type": "string" }, "assetStatus": { "enum": [ "READY", "EXPIRED", "DELETING", "DELETED" ], "type": "string" }, "byteLength": { "anyOf": [ { "description": "Resource size in bytes.", "type": "number" }, { "type": "null" } ], "nullable": true }, "content": { "anyOf": [ { "description": "Inline text content (e.g. lyrics).", "type": "string" }, { "type": "null" } ], "nullable": true }, "contentType": { "anyOf": [ { "description": "Resource content type.", "type": "string" }, { "type": "null" } ], "nullable": true }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "durationSec": { "anyOf": [ { "description": "Resource duration in seconds.", "type": "number" }, { "type": "null" } ], "nullable": true }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "id": { "description": "Stable resource id (OmnAPI resource id).", "type": "string" }, "index": { "description": "Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.", "minimum": 0, "type": "number" }, "metadata": { "anyOf": [ { "patternProperties": { "^(.*)$": {} }, "type": "object" }, { "type": "null" } ], "nullable": true }, "retainedUntil": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "role": { "enum": [ "candidate", "final", "stem", "fallback", "output" ], "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "enum": [ "MUSIC", "IMAGE", "VIDEO", "AUDIO", "TEXT", "METADATA" ], "type": "string" }, "url": { "anyOf": [ { "description": "Presigned/public URL.", "type": "string" }, { "type": "null" } ], "nullable": true }, "urlExpiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true } }, "required": [ "id", "index", "role", "type" ], "type": "object" }, "type": "array" }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "description": "Task unique identifier", "type": "string" } }, "required": [ "taskId", "status", "creditsRequired", "creditsCharged", "outputResults", "errorCode", "errorMessage", "processingDuration", "processingDurationText" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsCharged": { "anyOf": [ { "description": "Exact credits actually charged", "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "creditsRequired": { "description": "Exact credits deducted to start the task", "minimum": 0, "type": "number" }, "errorCode": { "anyOf": [ { "description": "Error code if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "errorMessage": { "anyOf": [ { "description": "Error message if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "outputResults": { "anyOf": [ { "additionalProperties": false, "properties": { "clipId": { "type": "string" }, "lines": { "items": { "additionalProperties": false, "properties": { "end": { "minimum": 0, "type": "number" }, "section": { "type": "string" }, "start": { "minimum": 0, "type": "number" }, "text": { "type": "string" }, "words": { "items": { "additionalProperties": false, "properties": { "confidence": { "type": "number" }, "end": { "minimum": 0, "type": "number" }, "start": { "minimum": 0, "type": "number" }, "success": { "type": "boolean" }, "word": { "type": "string" } }, "required": [ "word", "start", "end" ], "type": "object" }, "type": "array" } }, "required": [ "text", "start", "end", "words" ], "type": "object" }, "type": "array" }, "waveform_data": { "items": { "type": "number" }, "type": "array" }, "words": { "items": { "additionalProperties": false, "properties": { "confidence": { "type": "number" }, "end": { "minimum": 0, "type": "number" }, "start": { "minimum": 0, "type": "number" }, "success": { "type": "boolean" }, "word": { "type": "string" } }, "required": [ "word", "start", "end" ], "type": "object" }, "type": "array" } }, "required": [ "clipId", "words", "lines", "waveform_data" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "pollUrl": { "anyOf": [ { "description": "Set only when the synchronous wait timed out (HTTP 202, status=PROCESSING). The task is still running — poll this URL for the final result. Null/absent on terminal responses.", "type": "string" }, { "type": "null" } ], "nullable": true }, "processingDuration": { "anyOf": [ { "description": "Processing duration in milliseconds", "type": "number" }, { "type": "null" } ], "nullable": true }, "processingDurationText": { "anyOf": [ { "description": "Human-readable processing duration, e.g. 16.2s", "type": "string" }, { "type": "null" } ], "nullable": true }, "resources": { "description": "Standardized resources produced by the task", "items": { "description": "A consumable resource produced by the task.", "properties": { "assetId": { "description": "Stable OmnAPI-owned asset id when available.", "type": "string" }, "assetStatus": { "enum": [ "READY", "EXPIRED", "DELETING", "DELETED" ], "type": "string" }, "byteLength": { "anyOf": [ { "description": "Resource size in bytes.", "type": "number" }, { "type": "null" } ], "nullable": true }, "content": { "anyOf": [ { "description": "Inline text content (e.g. lyrics).", "type": "string" }, { "type": "null" } ], "nullable": true }, "contentType": { "anyOf": [ { "description": "Resource content type.", "type": "string" }, { "type": "null" } ], "nullable": true }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "durationSec": { "anyOf": [ { "description": "Resource duration in seconds.", "type": "number" }, { "type": "null" } ], "nullable": true }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "id": { "description": "Stable resource id (OmnAPI resource id).", "type": "string" }, "index": { "description": "Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.", "minimum": 0, "type": "number" }, "metadata": { "anyOf": [ { "patternProperties": { "^(.*)$": {} }, "type": "object" }, { "type": "null" } ], "nullable": true }, "retainedUntil": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "role": { "enum": [ "candidate", "final", "stem", "fallback", "output" ], "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "enum": [ "MUSIC", "IMAGE", "VIDEO", "AUDIO", "TEXT", "METADATA" ], "type": "string" }, "url": { "anyOf": [ { "description": "Presigned/public URL.", "type": "string" }, { "type": "null" } ], "nullable": true }, "urlExpiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true } }, "required": [ "id", "index", "role", "type" ], "type": "object" }, "type": "array" }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "description": "Task unique identifier", "type": "string" } }, "required": [ "taskId", "status", "creditsRequired", "creditsCharged", "outputResults", "errorCode", "errorMessage", "processingDuration", "processingDurationText" ], "type": "object" } } }, "description": "Response for status 202", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "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." }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 422" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Get aligned lyrics timeline", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/suno/generations": { "get": { "description": "Cursor-paginated product history. The cursor is opaque; do not construct it client-side.", "operationId": "getApiV1SunoGenerations", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 100, "minimum": 1, "type": "number" }, "description": "Maximum number of items to return." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" }, "description": "Opaque pagination cursor returned as nextCursor; omit it on the first page." } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "hasMore": { "type": "boolean" }, "items": { "items": { "additionalProperties": false, "properties": { "autoFinalize": { "type": "boolean" }, "billing": { "additionalProperties": false, "properties": { "creditsCharged": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "creditsRequired": { "minimum": 0, "type": "number" }, "pricing": { "anyOf": [ { "additionalProperties": false, "properties": { "adjustmentCredits": { "description": "chargedCredits - baseCredits", "type": "number" }, "baseCredits": { "description": "Standard quoted credits before customer pricing adjustment", "type": "number" }, "billingIncrementCredits": { "description": "Smallest customer charge increment", "minimum": 0.0001, "type": "number" }, "calculatedCredits": { "description": "Precise whole-order subtotal before settlement rounding", "type": "number" }, "chargedCredits": { "description": "Frozen task charge. New whole-credit quotes are integers; historical fractional quotes retain up to four decimal places.", "minimum": 0, "type": "number" }, "quoteVersion": { "description": "Pricing quote version stored with the task", "type": "number" }, "settlementPolicyVersion": { "description": "Versioned customer settlement policy", "type": "string" }, "settlementRoundingCredits": { "description": "Whole-order rounding adjustment added at settlement", "minimum": 0, "type": "number" }, "source": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "customer_rule", "type": "string" } ], "description": "Public pricing source category" } }, "required": [ "baseCredits", "chargedCredits", "adjustmentCredits", "source", "quoteVersion" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "refunded": { "type": "boolean" }, "settlementStatus": { "enum": [ "PENDING", "CHARGED", "REFUNDED" ], "type": "string" } }, "required": [ "creditsRequired", "creditsCharged", "refunded", "settlementStatus", "pricing" ], "type": "object" }, "clips": { "items": { "additionalProperties": false, "properties": { "accessLevel": { "enum": [ "owned", "shared", "external" ], "type": "string" }, "audioUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "clipId": { "description": "Suno clip identifier (`mid`); do not substitute an OmnAPI resource identifier.", "type": "string" }, "createdAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "deliveryStatus": { "enum": [ "submitted", "queued", "streaming", "complete", "error" ], "type": "string" }, "duration": { "anyOf": [ { "description": "Clip duration in seconds. Missing eventually-consistent metadata is repaired on later reads.", "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "imageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "index": { "minimum": 0, "type": "number" }, "instrumental": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "nullable": true }, "majorModelVersion": { "anyOf": [ { "description": "Exact Suno major_model_version value reported for this clip, for example v4.5-all.", "type": "string" }, { "type": "null" } ], "nullable": true }, "model": { "anyOf": [ { "description": "Compatibility model label. Prefer modelCode, providerModelName and majorModelVersion for unambiguous integrations.", "type": "string" }, { "type": "null" } ], "nullable": true }, "modelCode": { "anyOf": [ { "description": "Canonical OmnAPI model code selected for an owned generation. Null when a clip is read directly from Suno without a local task.", "type": "string" }, { "type": "null" } ], "nullable": true }, "playable": { "type": "boolean" }, "playback": { "additionalProperties": false, "properties": { "delivery": { "enum": [ "none", "chunked", "progressive" ], "type": "string" }, "expiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "mimeType": { "anyOf": [ { "anyOf": [ { "const": "audio/mpeg", "type": "string" }, { "const": "audio/mp4", "type": "string" } ] }, { "type": "null" } ], "nullable": true }, "retryAfterMs": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "seekable": { "type": "boolean" }, "sessionCreateUrl": { "anyOf": [ { "deprecated": true, "description": "Deprecated compatibility field. New integrations should use playback.url directly; no separate playback-session request is needed.", "type": "string" }, { "type": "null" } ], "nullable": true }, "state": { "enum": [ "preparing", "live", "final", "error", "unavailable" ], "type": "string" }, "url": { "anyOf": [ { "description": "Current playback URL. Live Generation reads provide a temporary URL; final reads provide the completed audio URL. Resolve relative URLs against the API base URL and open them without an API key. A null value means to wait and query the Generation again. Treat the complete URL as private and do not construct or modify it.", "type": "string" }, { "type": "null" } ], "nullable": true } }, "required": [ "state", "url", "mimeType", "delivery", "seekable", "expiresAt", "retryAfterMs", "sessionCreateUrl" ], "type": "object" }, "prompt": { "anyOf": [ { "description": "Generation prompt for owned clips only. Shared and external clips always return null.", "type": "string" }, { "type": "null" } ], "nullable": true }, "providerModelName": { "anyOf": [ { "description": "Exact Suno model_name value reported for this clip, for example chirp-hawk.", "type": "string" }, { "type": "null" } ], "nullable": true }, "role": { "enum": [ "candidate", "final" ], "type": "string" }, "tags": { "anyOf": [ { "description": "Public style tags for owned and shared clips. Null for external clips or before metadata propagation completes.", "type": "string" }, { "type": "null" } ], "nullable": true }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "updatedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "videoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true } }, "required": [ "clipId", "accessLevel", "index", "role", "deliveryStatus", "title", "tags", "prompt", "model", "modelCode", "providerModelName", "majorModelVersion", "instrumental", "audioUrl", "imageUrl", "videoUrl", "playable", "playback", "duration", "errorCode", "errorMessage", "createdAt", "updatedAt" ], "type": "object" }, "type": "array" }, "createdAt": { "format": "date-time", "type": "string" }, "deliveryStatus": { "anyOf": [ { "anyOf": [ { "const": "submitted", "type": "string" }, { "const": "queued", "type": "string" }, { "const": "streaming", "type": "string" }, { "const": "complete", "type": "string" }, { "const": "error", "type": "string" } ] }, { "type": "null" } ], "nullable": true }, "failureReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "finalClipId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "finalUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "generationId": { "description": "Canonical OmnAPI Suno product ID. It equals the originating taskId.", "type": "string" }, "partialFailure": { "description": "True when the generation completed with at least one successful clip and at least one failed clip.", "type": "boolean" }, "phase": { "enum": [ "accepted", "generating", "finalizing", "completed", "failed" ], "type": "string" }, "progress": { "maximum": 100, "minimum": 0, "type": "number" }, "refundable": { "type": "boolean" }, "retryable": { "type": "boolean" }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "minimum": 0, "type": "number" }, "warningCodes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "generationId", "taskId", "version", "status", "phase", "progress", "deliveryStatus", "partialFailure", "clips", "finalClipId", "finalUrl", "autoFinalize", "failureReason", "retryable", "refundable", "billing", "warningCodes", "createdAt", "updatedAt" ], "type": "object" }, "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true } }, "required": [ "items", "nextCursor", "hasMore" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Forbidden: the API key lacks the required scope or its IP policy rejects this request." }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "List Suno generations", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/suno/generations/{generationId}": { "get": { "description": "Canonical product view for one Suno generation. It exposes every candidate's submitted/queued/streaming/complete/error lifecycle independently. Use GET /api/v1/tasks/{taskId} for execution and billing diagnostics.", "operationId": "getApiV1SunoGenerationsByGenerationId", "parameters": [ { "in": "path", "name": "generationId", "required": true, "schema": { "minLength": 1, "type": "string" }, "description": "Suno Generation identifier returned by song creation." } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "autoFinalize": { "type": "boolean" }, "billing": { "additionalProperties": false, "properties": { "creditsCharged": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "creditsRequired": { "minimum": 0, "type": "number" }, "pricing": { "anyOf": [ { "additionalProperties": false, "properties": { "adjustmentCredits": { "description": "chargedCredits - baseCredits", "type": "number" }, "baseCredits": { "description": "Standard quoted credits before customer pricing adjustment", "type": "number" }, "billingIncrementCredits": { "description": "Smallest customer charge increment", "minimum": 0.0001, "type": "number" }, "calculatedCredits": { "description": "Precise whole-order subtotal before settlement rounding", "type": "number" }, "chargedCredits": { "description": "Frozen task charge. New whole-credit quotes are integers; historical fractional quotes retain up to four decimal places.", "minimum": 0, "type": "number" }, "quoteVersion": { "description": "Pricing quote version stored with the task", "type": "number" }, "settlementPolicyVersion": { "description": "Versioned customer settlement policy", "type": "string" }, "settlementRoundingCredits": { "description": "Whole-order rounding adjustment added at settlement", "minimum": 0, "type": "number" }, "source": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "customer_rule", "type": "string" } ], "description": "Public pricing source category" } }, "required": [ "baseCredits", "chargedCredits", "adjustmentCredits", "source", "quoteVersion" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "refunded": { "type": "boolean" }, "settlementStatus": { "enum": [ "PENDING", "CHARGED", "REFUNDED" ], "type": "string" } }, "required": [ "creditsRequired", "creditsCharged", "refunded", "settlementStatus", "pricing" ], "type": "object" }, "clips": { "items": { "additionalProperties": false, "properties": { "accessLevel": { "enum": [ "owned", "shared", "external" ], "type": "string" }, "audioUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "clipId": { "description": "Suno clip identifier (`mid`); do not substitute an OmnAPI resource identifier.", "type": "string" }, "createdAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "deliveryStatus": { "enum": [ "submitted", "queued", "streaming", "complete", "error" ], "type": "string" }, "duration": { "anyOf": [ { "description": "Clip duration in seconds. Missing eventually-consistent metadata is repaired on later reads.", "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "imageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "index": { "minimum": 0, "type": "number" }, "instrumental": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "nullable": true }, "majorModelVersion": { "anyOf": [ { "description": "Exact Suno major_model_version value reported for this clip, for example v4.5-all.", "type": "string" }, { "type": "null" } ], "nullable": true }, "model": { "anyOf": [ { "description": "Compatibility model label. Prefer modelCode, providerModelName and majorModelVersion for unambiguous integrations.", "type": "string" }, { "type": "null" } ], "nullable": true }, "modelCode": { "anyOf": [ { "description": "Canonical OmnAPI model code selected for an owned generation. Null when a clip is read directly from Suno without a local task.", "type": "string" }, { "type": "null" } ], "nullable": true }, "playable": { "type": "boolean" }, "playback": { "additionalProperties": false, "properties": { "delivery": { "enum": [ "none", "chunked", "progressive" ], "type": "string" }, "expiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "mimeType": { "anyOf": [ { "anyOf": [ { "const": "audio/mpeg", "type": "string" }, { "const": "audio/mp4", "type": "string" } ] }, { "type": "null" } ], "nullable": true }, "retryAfterMs": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "seekable": { "type": "boolean" }, "sessionCreateUrl": { "anyOf": [ { "deprecated": true, "description": "Deprecated compatibility field. New integrations should use playback.url directly; no separate playback-session request is needed.", "type": "string" }, { "type": "null" } ], "nullable": true }, "state": { "enum": [ "preparing", "live", "final", "error", "unavailable" ], "type": "string" }, "url": { "anyOf": [ { "description": "Current playback URL. Live Generation reads provide a temporary URL; final reads provide the completed audio URL. Resolve relative URLs against the API base URL and open them without an API key. A null value means to wait and query the Generation again. Treat the complete URL as private and do not construct or modify it.", "type": "string" }, { "type": "null" } ], "nullable": true } }, "required": [ "state", "url", "mimeType", "delivery", "seekable", "expiresAt", "retryAfterMs", "sessionCreateUrl" ], "type": "object" }, "prompt": { "anyOf": [ { "description": "Generation prompt for owned clips only. Shared and external clips always return null.", "type": "string" }, { "type": "null" } ], "nullable": true }, "providerModelName": { "anyOf": [ { "description": "Exact Suno model_name value reported for this clip, for example chirp-hawk.", "type": "string" }, { "type": "null" } ], "nullable": true }, "role": { "enum": [ "candidate", "final" ], "type": "string" }, "tags": { "anyOf": [ { "description": "Public style tags for owned and shared clips. Null for external clips or before metadata propagation completes.", "type": "string" }, { "type": "null" } ], "nullable": true }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "updatedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "videoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true } }, "required": [ "clipId", "accessLevel", "index", "role", "deliveryStatus", "title", "tags", "prompt", "model", "modelCode", "providerModelName", "majorModelVersion", "instrumental", "audioUrl", "imageUrl", "videoUrl", "playable", "playback", "duration", "errorCode", "errorMessage", "createdAt", "updatedAt" ], "type": "object" }, "type": "array" }, "createdAt": { "format": "date-time", "type": "string" }, "deliveryStatus": { "anyOf": [ { "anyOf": [ { "const": "submitted", "type": "string" }, { "const": "queued", "type": "string" }, { "const": "streaming", "type": "string" }, { "const": "complete", "type": "string" }, { "const": "error", "type": "string" } ] }, { "type": "null" } ], "nullable": true }, "failureReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "finalClipId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "finalUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "generationId": { "description": "Canonical OmnAPI Suno product ID. It equals the originating taskId.", "type": "string" }, "partialFailure": { "description": "True when the generation completed with at least one successful clip and at least one failed clip.", "type": "boolean" }, "phase": { "enum": [ "accepted", "generating", "finalizing", "completed", "failed" ], "type": "string" }, "progress": { "maximum": 100, "minimum": 0, "type": "number" }, "refundable": { "type": "boolean" }, "retryable": { "type": "boolean" }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "version": { "minimum": 0, "type": "number" }, "warningCodes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "generationId", "taskId", "version", "status", "phase", "progress", "deliveryStatus", "partialFailure", "clips", "finalClipId", "finalUrl", "autoFinalize", "failureReason", "retryable", "refundable", "billing", "warningCodes", "createdAt", "updatedAt" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Forbidden: the API key lacks the required scope or its IP policy rejects this request." }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "Get a Suno generation", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/suno/lyrics": { "post": { "description": "Create lyrics without changing the established request contract. `candidates=2` succeeds only after both ordered A/B candidates complete. Each completed text resource may include `metadata.stylePrompt` and compatibility `metadata.tags: [stylePrompt]`; style expansion is best-effort and never turns completed lyrics into a failed Task. The optional `lyricsModel` currently accepts only `default`. Returns a task id — poll `GET /api/v1/tasks/{taskId}` for the result. `Idempotency-Key` is optional but recommended for safe client retries. For a synchronous lyrics call, use `POST /api/v1/lyrics/generate`.", "operationId": "postApiV1SunoLyrics", "parameters": [ { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "candidates": { "enum": [ 1, 2 ], "type": "integer", "description": "Number of independent candidates to generate." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "lyricsModel": { "description": "Only the stable \"default\" lyrics model is supported for candidates=2.", "maxLength": 100, "type": "string" }, "prompt": { "maxLength": 3000, "type": "string", "description": "Primary creative or operation instruction." }, "source": { "description": "Optional caller label retained in Task audit input for candidates=2.", "maxLength": 100, "type": "string" } }, "required": [ "prompt" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "candidates": { "enum": [ 1, 2 ], "type": "integer", "description": "Number of independent candidates to generate." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "lyricsModel": { "description": "Only the stable \"default\" lyrics model is supported for candidates=2.", "maxLength": 100, "type": "string" }, "prompt": { "maxLength": 3000, "type": "string", "description": "Primary creative or operation instruction." }, "source": { "description": "Optional caller label retained in Task audit input for candidates=2.", "maxLength": 100, "type": "string" } }, "required": [ "prompt" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "candidates": { "enum": [ 1, 2 ], "type": "integer", "description": "Number of independent candidates to generate." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "lyricsModel": { "description": "Only the stable \"default\" lyrics model is supported for candidates=2.", "maxLength": 100, "type": "string" }, "prompt": { "maxLength": 3000, "type": "string", "description": "Primary creative or operation instruction." }, "source": { "description": "Optional caller label retained in Task audit input for candidates=2.", "maxLength": 100, "type": "string" } }, "required": [ "prompt" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsRequired": { "minimum": 0, "type": "number" }, "estimatedCompletionTime": { "anyOf": [ { "description": "Estimated completion time as an RFC 3339 string.", "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "links": { "additionalProperties": false, "properties": { "final": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "resource": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "task": { "type": "string" } }, "required": [ "task", "resource", "final" ], "type": "object" }, "pricing": { "additionalProperties": false, "properties": { "adjustmentCredits": { "description": "chargedCredits - baseCredits", "type": "number" }, "baseCredits": { "description": "Standard quoted credits before customer pricing adjustment", "type": "number" }, "billingIncrementCredits": { "description": "Smallest customer charge increment", "minimum": 0.0001, "type": "number" }, "calculatedCredits": { "description": "Precise whole-order subtotal before settlement rounding", "type": "number" }, "chargedCredits": { "description": "Credits charged for this create request", "minimum": 0, "type": "number" }, "quoteVersion": { "description": "Pricing quote version stored with the task", "type": "number" }, "settlementPolicyVersion": { "description": "Versioned customer settlement policy", "type": "string" }, "settlementRoundingCredits": { "description": "Whole-order rounding adjustment added at settlement", "minimum": 0, "type": "number" }, "source": { "enum": [ "standard", "customer_rule" ], "type": "string" } }, "required": [ "baseCredits", "chargedCredits", "adjustmentCredits", "source", "quoteVersion" ], "type": "object" }, "product": { "additionalProperties": false, "properties": { "autoFinalize": { "description": "Whether the product should finalize automatically", "type": "boolean" }, "deliveryStatus": { "anyOf": [ { "description": "Product-level delivery status when applicable", "type": "string" }, { "type": "null" } ], "nullable": true }, "featureCode": { "description": "Resolved feature code", "type": "string" }, "modelCode": { "description": "Resolved model code", "type": "string" }, "providerCode": { "description": "Resolved provider code", "type": "string" }, "resourceId": { "anyOf": [ { "description": "Product resource id when created synchronously", "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "description": "Product family for this task, e.g. suno, producer, mv", "type": "string" } }, "required": [ "type", "providerCode", "modelCode", "featureCode", "resourceId" ], "type": "object" }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "type": "string" }, "warningCodes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "taskId", "status", "creditsRequired", "requestId", "links", "pricing", "product", "warningCodes" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "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." }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 422" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Generate Lyrics", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/suno/songs": { "post": { "description": "Create a song from text, a confirmed public Voice, or a managed upload + Extend/Cover workflow.", "operationId": "postApiV1SunoSongs", "parameters": [ { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } }, { "description": "Set to respond-async to skip the acknowledgement wait and return the generation receipt immediately.", "in": "header", "name": "Prefer", "required": false, "schema": { "enum": [ "respond-async" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "audio": { "additionalProperties": false, "properties": { "extensionType": { "enum": [ "mp3", "wav", "m4a", "flac", "ogg" ], "type": "string", "description": "Audio filename or media extension hint." }, "url": { "description": "Publicly retrievable audio URL used only by upload-extend or upload-cover.", "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object", "description": "Public audio source and format information." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "continueAt": { "description": "Timestamp in seconds to continue from. Values beyond the source duration are forwarded unchanged and Suno continues from the clip end.", "minimum": 0, "type": "number" }, "continuedAlignedPrompt": { "maxLength": 5000, "type": "string", "description": "Aligned continuation prompt used for an Extend operation." }, "controlSliders": { "properties": { "audio_weight": { "maximum": 1, "minimum": 0, "type": "number", "description": "Source-audio adherence weight from 0 to 1." }, "style_weight": { "maximum": 1, "minimum": 0, "type": "number", "description": "Style adherence weight from 0 to 1." }, "weirdness_constraint": { "maximum": 1, "minimum": 0, "type": "number", "description": "Creative-variation constraint from 0 to 1." } }, "type": "object", "description": "Optional bounded generation-control weights." }, "instrumental": { "type": "boolean", "description": "Whether to generate an instrumental result." }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "mode": { "description": "Generation mode. Vox accepts the three v6 generation models with account-specific permission checks; unsupported model combinations are rejected before task creation. Upload modes atomically import the supplied audio and then Extend or Cover it; standalone upload is not exposed.", "pattern": "^(simple|custom|vox|upload-extend|upload-cover)$", "type": "string" }, "model": { "enum": [ "chirp-hawk", "chirp-hawk-wild", "chirp-goose", "chirp-auk-turbo", "chirp-v4", "chirp-auk", "chirp-bluejay", "chirp-crow", "chirp-fenix" ], "type": "string", "description": "Model identifier accepted by this schema variant." }, "negativeTags": { "maxLength": 1000, "type": "string", "description": "Negative music-style tags or exclusions." }, "prompt": { "maxLength": 5000, "type": "string", "description": "Primary creative or operation instruction." }, "tags": { "maxLength": 1000, "type": "string", "description": "Style tags or caller labels, as defined by this schema." }, "title": { "maxLength": 100, "type": "string", "description": "Optional customer-facing title." }, "voiceId": { "type": "string", "description": "Reusable public Suno Voice identifier." } }, "required": [ "mode" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "audio": { "additionalProperties": false, "properties": { "extensionType": { "enum": [ "mp3", "wav", "m4a", "flac", "ogg" ], "type": "string", "description": "Audio filename or media extension hint." }, "url": { "description": "Publicly retrievable audio URL used only by upload-extend or upload-cover.", "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object", "description": "Public audio source and format information." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "continueAt": { "description": "Timestamp in seconds to continue from. Values beyond the source duration are forwarded unchanged and Suno continues from the clip end.", "minimum": 0, "type": "number" }, "continuedAlignedPrompt": { "maxLength": 5000, "type": "string", "description": "Aligned continuation prompt used for an Extend operation." }, "controlSliders": { "properties": { "audio_weight": { "maximum": 1, "minimum": 0, "type": "number", "description": "Source-audio adherence weight from 0 to 1." }, "style_weight": { "maximum": 1, "minimum": 0, "type": "number", "description": "Style adherence weight from 0 to 1." }, "weirdness_constraint": { "maximum": 1, "minimum": 0, "type": "number", "description": "Creative-variation constraint from 0 to 1." } }, "type": "object", "description": "Optional bounded generation-control weights." }, "instrumental": { "type": "boolean", "description": "Whether to generate an instrumental result." }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "mode": { "description": "Generation mode. Vox accepts the three v6 generation models with account-specific permission checks; unsupported model combinations are rejected before task creation. Upload modes atomically import the supplied audio and then Extend or Cover it; standalone upload is not exposed.", "pattern": "^(simple|custom|vox|upload-extend|upload-cover)$", "type": "string" }, "model": { "enum": [ "chirp-hawk", "chirp-hawk-wild", "chirp-goose", "chirp-auk-turbo", "chirp-v4", "chirp-auk", "chirp-bluejay", "chirp-crow", "chirp-fenix" ], "type": "string", "description": "Model identifier accepted by this schema variant." }, "negativeTags": { "maxLength": 1000, "type": "string", "description": "Negative music-style tags or exclusions." }, "prompt": { "maxLength": 5000, "type": "string", "description": "Primary creative or operation instruction." }, "tags": { "maxLength": 1000, "type": "string", "description": "Style tags or caller labels, as defined by this schema." }, "title": { "maxLength": 100, "type": "string", "description": "Optional customer-facing title." }, "voiceId": { "type": "string", "description": "Reusable public Suno Voice identifier." } }, "required": [ "mode" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "audio": { "additionalProperties": false, "properties": { "extensionType": { "enum": [ "mp3", "wav", "m4a", "flac", "ogg" ], "type": "string", "description": "Audio filename or media extension hint." }, "url": { "description": "Publicly retrievable audio URL used only by upload-extend or upload-cover.", "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object", "description": "Public audio source and format information." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "continueAt": { "description": "Timestamp in seconds to continue from. Values beyond the source duration are forwarded unchanged and Suno continues from the clip end.", "minimum": 0, "type": "number" }, "continuedAlignedPrompt": { "maxLength": 5000, "type": "string", "description": "Aligned continuation prompt used for an Extend operation." }, "controlSliders": { "properties": { "audio_weight": { "maximum": 1, "minimum": 0, "type": "number", "description": "Source-audio adherence weight from 0 to 1." }, "style_weight": { "maximum": 1, "minimum": 0, "type": "number", "description": "Style adherence weight from 0 to 1." }, "weirdness_constraint": { "maximum": 1, "minimum": 0, "type": "number", "description": "Creative-variation constraint from 0 to 1." } }, "type": "object", "description": "Optional bounded generation-control weights." }, "instrumental": { "type": "boolean", "description": "Whether to generate an instrumental result." }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "mode": { "description": "Generation mode. Vox accepts the three v6 generation models with account-specific permission checks; unsupported model combinations are rejected before task creation. Upload modes atomically import the supplied audio and then Extend or Cover it; standalone upload is not exposed.", "pattern": "^(simple|custom|vox|upload-extend|upload-cover)$", "type": "string" }, "model": { "enum": [ "chirp-hawk", "chirp-hawk-wild", "chirp-goose", "chirp-auk-turbo", "chirp-v4", "chirp-auk", "chirp-bluejay", "chirp-crow", "chirp-fenix" ], "type": "string", "description": "Model identifier accepted by this schema variant." }, "negativeTags": { "maxLength": 1000, "type": "string", "description": "Negative music-style tags or exclusions." }, "prompt": { "maxLength": 5000, "type": "string", "description": "Primary creative or operation instruction." }, "tags": { "maxLength": 1000, "type": "string", "description": "Style tags or caller labels, as defined by this schema." }, "title": { "maxLength": 100, "type": "string", "description": "Optional customer-facing title." }, "voiceId": { "type": "string", "description": "Reusable public Suno Voice identifier." } }, "required": [ "mode" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "autoFinalize": { "type": "boolean" }, "clipIds": { "items": { "type": "string" }, "type": "array" }, "creditsRequired": { "minimum": 0, "type": "number" }, "deliveryStatus": { "anyOf": [ { "anyOf": [ { "const": "submitted", "type": "string" }, { "const": "queued", "type": "string" }, { "const": "streaming", "type": "string" }, { "const": "complete", "type": "string" }, { "const": "error", "type": "string" } ] }, { "type": "null" } ], "nullable": true }, "estimatedCompletionTime": { "anyOf": [ { "description": "Estimated completion time as an RFC 3339 string.", "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "finalUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "generationId": { "type": "string" }, "links": { "additionalProperties": false, "properties": { "final": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "resource": { "type": "string" }, "task": { "type": "string" } }, "required": [ "task", "resource", "final" ], "type": "object" }, "pollUrl": { "type": "string" }, "pricing": { "additionalProperties": false, "properties": { "adjustmentCredits": { "description": "chargedCredits - baseCredits", "type": "number" }, "baseCredits": { "description": "Standard quoted credits before customer pricing adjustment", "type": "number" }, "billingIncrementCredits": { "description": "Smallest customer charge increment", "minimum": 0.0001, "type": "number" }, "calculatedCredits": { "description": "Precise whole-order subtotal before settlement rounding", "type": "number" }, "chargedCredits": { "description": "Credits charged for this create request", "minimum": 0, "type": "number" }, "quoteVersion": { "description": "Pricing quote version stored with the task", "type": "number" }, "settlementPolicyVersion": { "description": "Versioned customer settlement policy", "type": "string" }, "settlementRoundingCredits": { "description": "Whole-order rounding adjustment added at settlement", "minimum": 0, "type": "number" }, "source": { "enum": [ "standard", "customer_rule" ], "type": "string" } }, "required": [ "baseCredits", "chargedCredits", "adjustmentCredits", "source", "quoteVersion" ], "type": "object" }, "product": { "additionalProperties": false, "properties": { "autoFinalize": { "type": "boolean" }, "deliveryStatus": { "anyOf": [ { "anyOf": [ { "const": "submitted", "type": "string" }, { "const": "queued", "type": "string" }, { "const": "streaming", "type": "string" }, { "const": "complete", "type": "string" }, { "const": "error", "type": "string" } ] }, { "type": "null" } ], "nullable": true }, "featureCode": { "type": "string" }, "modelCode": { "type": "string" }, "providerCode": { "const": "suno", "type": "string" }, "resourceId": { "type": "string" }, "type": { "const": "suno", "type": "string" } }, "required": [ "type", "providerCode", "modelCode", "featureCode", "resourceId", "deliveryStatus", "autoFinalize" ], "type": "object" }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "type": "string" }, "viewUrl": { "type": "string" }, "warningCodes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "taskId", "generationId", "status", "creditsRequired", "requestId", "links", "pricing", "product", "warningCodes", "clipIds", "pollUrl", "viewUrl", "finalUrl", "deliveryStatus", "autoFinalize" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "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." }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 422" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Generate Song", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/suno/storage": { "get": { "description": "Read availability, the current published storage rate, active subscription, billable bytes and unpaid usage. Check available before offering paid storage enrollment. All amounts are integer credit units represented as strings.", "operationId": "getApiV1SunoStorage", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "audioFreeDays": { "type": "number" }, "available": { "type": "boolean" }, "billableBytes": { "type": "string" }, "billingUnit": { "type": "string" }, "cancellationGraceDays": { "type": "number" }, "fixedRetentionDays": { "type": "number" }, "publishedRateUnitsPerGbMonth": { "type": "string" }, "subscription": { "anyOf": [ { "type": "null" }, { "properties": { "graceUntil": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "meteredThrough": { "format": "date-time", "type": "string" }, "rateUnitsPerGbMonth": { "type": "string" }, "status": { "type": "string" }, "stoppedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "status", "rateUnitsPerGbMonth", "meteredThrough", "graceUntil", "stoppedAt" ], "type": "object" } ] }, "unpaidUnits": { "type": "string" } }, "required": [ "available", "publishedRateUnitsPerGbMonth", "billingUnit", "subscription", "billableBytes", "unpaidUnits", "fixedRetentionDays", "audioFreeDays", "cancellationGraceDays" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "Inspect Suno storage policy, rate and subscription", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] }, "put": { "description": "Explicitly accepts the published unit rate and includes currently live ordinary audio and future deliveries. WAV and timestamp lyrics stay fixed at 180 days. Billing starts after the first 14 days and settles daily. Cancellation stops accrual and grants a 7-day download grace period. Expired assets are not revived.", "operationId": "putApiV1SunoStorage", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "acceptedRateUnits": { "description": "Current publishedRateUnitsPerGbMonth accepted by the customer. Required to enable a new subscription; obtain it from GET /api/v1/suno/storage.", "pattern": "^[0-9]{1,10}$", "type": "string" }, "enabled": { "description": "True explicitly enables paid long-term ordinary audio storage; false cancels accrual and starts the download grace period.", "type": "boolean" } }, "required": [ "enabled" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "acceptedRateUnits": { "description": "Current publishedRateUnitsPerGbMonth accepted by the customer. Required to enable a new subscription; obtain it from GET /api/v1/suno/storage.", "pattern": "^[0-9]{1,10}$", "type": "string" }, "enabled": { "description": "True explicitly enables paid long-term ordinary audio storage; false cancels accrual and starts the download grace period.", "type": "boolean" } }, "required": [ "enabled" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "acceptedRateUnits": { "description": "Current publishedRateUnitsPerGbMonth accepted by the customer. Required to enable a new subscription; obtain it from GET /api/v1/suno/storage.", "pattern": "^[0-9]{1,10}$", "type": "string" }, "enabled": { "description": "True explicitly enables paid long-term ordinary audio storage; false cancels accrual and starts the download grace period.", "type": "boolean" } }, "required": [ "enabled" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "null" }, { "properties": { "graceUntil": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "meteredThrough": { "format": "date-time", "type": "string" }, "rateUnitsPerGbMonth": { "type": "string" }, "status": { "type": "string" }, "stoppedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "status", "rateUnitsPerGbMonth", "meteredThrough", "graceUntil", "stoppedAt" ], "type": "object" } ] } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Opt in to or cancel paid long-term audio storage", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/suno/storage/charges": { "get": { "description": "Exact usage, captured rate and debit state; amounts are integer credit units.", "operationId": "getApiV1SunoStorageCharges", "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 64, "type": "string" }, "description": "Opaque pagination cursor returned as nextCursor; omit it on the first page." }, { "in": "query", "name": "limit", "required": false, "schema": { "anyOf": [ { "default": 0, "format": "numeric", "type": "string" }, { "default": 20, "maximum": 100, "minimum": 1, "type": "number" } ], "default": 20, "maximum": 100, "minimum": 1 }, "description": "Maximum number of items to return." } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "items": { "items": { "properties": { "amountUnits": { "type": "string" }, "byteMilliseconds": { "type": "string" }, "from": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "rateUnitsPerGbMonth": { "type": "string" }, "status": { "type": "string" }, "until": { "format": "date-time", "type": "string" } }, "required": [ "id", "from", "until", "amountUnits", "byteMilliseconds", "rateUnitsPerGbMonth", "status" ], "type": "object" }, "type": "array" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "List Suno storage charges", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/suno/styles/recommend": { "get": { "description": "Style suggestions. Short sync-wait; returns 202 with taskId on timeout.", "operationId": "getApiV1SunoStylesRecommend", "parameters": [ { "in": "query", "name": "exclude", "required": false, "schema": { "description": "Comma-separated style names to exclude", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsCharged": { "anyOf": [ { "description": "Exact credits actually charged", "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "creditsRequired": { "description": "Exact credits deducted to start the task", "minimum": 0, "type": "number" }, "errorCode": { "anyOf": [ { "description": "Error code if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "errorMessage": { "anyOf": [ { "description": "Error message if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "outputResults": { "anyOf": [ { "additionalProperties": false, "properties": { "recommendStyles": { "items": { "type": "string" }, "type": "array" } }, "required": [ "recommendStyles" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "pollUrl": { "anyOf": [ { "description": "Set only when the synchronous wait timed out (HTTP 202, status=PROCESSING). The task is still running — poll this URL for the final result. Null/absent on terminal responses.", "type": "string" }, { "type": "null" } ], "nullable": true }, "processingDuration": { "anyOf": [ { "description": "Processing duration in milliseconds", "type": "number" }, { "type": "null" } ], "nullable": true }, "processingDurationText": { "anyOf": [ { "description": "Human-readable processing duration, e.g. 16.2s", "type": "string" }, { "type": "null" } ], "nullable": true }, "resources": { "description": "Standardized resources produced by the task", "items": { "description": "A consumable resource produced by the task.", "properties": { "assetId": { "description": "Stable OmnAPI-owned asset id when available.", "type": "string" }, "assetStatus": { "enum": [ "READY", "EXPIRED", "DELETING", "DELETED" ], "type": "string" }, "byteLength": { "anyOf": [ { "description": "Resource size in bytes.", "type": "number" }, { "type": "null" } ], "nullable": true }, "content": { "anyOf": [ { "description": "Inline text content (e.g. lyrics).", "type": "string" }, { "type": "null" } ], "nullable": true }, "contentType": { "anyOf": [ { "description": "Resource content type.", "type": "string" }, { "type": "null" } ], "nullable": true }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "durationSec": { "anyOf": [ { "description": "Resource duration in seconds.", "type": "number" }, { "type": "null" } ], "nullable": true }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "id": { "description": "Stable resource id (OmnAPI resource id).", "type": "string" }, "index": { "description": "Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.", "minimum": 0, "type": "number" }, "metadata": { "anyOf": [ { "patternProperties": { "^(.*)$": {} }, "type": "object" }, { "type": "null" } ], "nullable": true }, "retainedUntil": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "role": { "enum": [ "candidate", "final", "stem", "fallback", "output" ], "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "enum": [ "MUSIC", "IMAGE", "VIDEO", "AUDIO", "TEXT", "METADATA" ], "type": "string" }, "url": { "anyOf": [ { "description": "Presigned/public URL.", "type": "string" }, { "type": "null" } ], "nullable": true }, "urlExpiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true } }, "required": [ "id", "index", "role", "type" ], "type": "object" }, "type": "array" }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "description": "Task unique identifier", "type": "string" } }, "required": [ "taskId", "status", "creditsRequired", "creditsCharged", "outputResults", "errorCode", "errorMessage", "processingDuration", "processingDurationText" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsCharged": { "anyOf": [ { "description": "Exact credits actually charged", "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "creditsRequired": { "description": "Exact credits deducted to start the task", "minimum": 0, "type": "number" }, "errorCode": { "anyOf": [ { "description": "Error code if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "errorMessage": { "anyOf": [ { "description": "Error message if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "outputResults": { "anyOf": [ { "additionalProperties": false, "properties": { "recommendStyles": { "items": { "type": "string" }, "type": "array" } }, "required": [ "recommendStyles" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "pollUrl": { "anyOf": [ { "description": "Set only when the synchronous wait timed out (HTTP 202, status=PROCESSING). The task is still running — poll this URL for the final result. Null/absent on terminal responses.", "type": "string" }, { "type": "null" } ], "nullable": true }, "processingDuration": { "anyOf": [ { "description": "Processing duration in milliseconds", "type": "number" }, { "type": "null" } ], "nullable": true }, "processingDurationText": { "anyOf": [ { "description": "Human-readable processing duration, e.g. 16.2s", "type": "string" }, { "type": "null" } ], "nullable": true }, "resources": { "description": "Standardized resources produced by the task", "items": { "description": "A consumable resource produced by the task.", "properties": { "assetId": { "description": "Stable OmnAPI-owned asset id when available.", "type": "string" }, "assetStatus": { "enum": [ "READY", "EXPIRED", "DELETING", "DELETED" ], "type": "string" }, "byteLength": { "anyOf": [ { "description": "Resource size in bytes.", "type": "number" }, { "type": "null" } ], "nullable": true }, "content": { "anyOf": [ { "description": "Inline text content (e.g. lyrics).", "type": "string" }, { "type": "null" } ], "nullable": true }, "contentType": { "anyOf": [ { "description": "Resource content type.", "type": "string" }, { "type": "null" } ], "nullable": true }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "durationSec": { "anyOf": [ { "description": "Resource duration in seconds.", "type": "number" }, { "type": "null" } ], "nullable": true }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "id": { "description": "Stable resource id (OmnAPI resource id).", "type": "string" }, "index": { "description": "Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.", "minimum": 0, "type": "number" }, "metadata": { "anyOf": [ { "patternProperties": { "^(.*)$": {} }, "type": "object" }, { "type": "null" } ], "nullable": true }, "retainedUntil": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "role": { "enum": [ "candidate", "final", "stem", "fallback", "output" ], "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "enum": [ "MUSIC", "IMAGE", "VIDEO", "AUDIO", "TEXT", "METADATA" ], "type": "string" }, "url": { "anyOf": [ { "description": "Presigned/public URL.", "type": "string" }, { "type": "null" } ], "nullable": true }, "urlExpiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true } }, "required": [ "id", "index", "role", "type" ], "type": "object" }, "type": "array" }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "description": "Task unique identifier", "type": "string" } }, "required": [ "taskId", "status", "creditsRequired", "creditsCharged", "outputResults", "errorCode", "errorMessage", "processingDuration", "processingDurationText" ], "type": "object" } } }, "description": "Response for status 202", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "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." }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 422" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Recommend Styles", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/suno/voices": { "get": { "description": "Lists only fully completed public Voices created by the current OmnAPI user. Private, test, intermediate, and partially completed Voices are excluded.", "operationId": "getApiV1SunoVoices", "parameters": [ { "in": "query", "name": "page", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "One-based page number." } }, { "in": "query", "name": "pageSize", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Voices per page." } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "currentPage": { "minimum": 1, "type": "number" }, "pageSize": { "maximum": 100, "minimum": 1, "type": "number" }, "totalResults": { "minimum": 0, "type": "number" }, "voices": { "items": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": "string" }, "imageUrl": { "type": "string" }, "name": { "type": "string" }, "sourceClipId": { "type": "string" }, "voiceId": { "type": "string" }, "voiceType": { "type": "string" } }, "required": [ "voiceId" ], "type": "object" }, "type": "array" } }, "required": [ "voices", "currentPage", "pageSize", "totalResults" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Forbidden: the API key lacks the required scope or its IP policy rejects this request." }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "List Voices", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] }, "post": { "description": "Creates a public Voice from verified recordings. First obtain a verification phrase, record it, then submit `verificationPhraseTaskId`, the verification recording URL, and the clean singing URL. Only the final public Voice is returned.", "operationId": "postApiV1SunoVoices", "parameters": [ { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "description": { "maxLength": 2000, "type": "string", "description": "Optional customer-facing resource description." }, "imageUrl": { "description": "Optional public image URL for the resulting Voice.", "format": "uri", "type": "string" }, "name": { "maxLength": 100, "type": "string", "description": "Customer-facing resource name." }, "verificationAudioUrl": { "description": "Recording of the requested verification phrase from the same speaker.", "format": "uri", "type": "string" }, "verificationExtensionType": { "enum": [ "mp3", "wav", "m4a", "flac", "ogg" ], "type": "string", "description": "Verification recording extension hint." }, "verificationPhraseTaskId": { "minLength": 1, "type": "string", "description": "Completed verification-phrase Task identifier." }, "voiceAudioUrl": { "description": "Clean singing recording URL used to create the public Voice.", "format": "uri", "type": "string" }, "voiceExtensionType": { "enum": [ "mp3", "wav", "m4a", "flac", "ogg" ], "type": "string", "description": "Voice recording extension hint." } }, "required": [ "voiceAudioUrl", "verificationAudioUrl", "verificationPhraseTaskId" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "description": { "maxLength": 2000, "type": "string", "description": "Optional customer-facing resource description." }, "imageUrl": { "description": "Optional public image URL for the resulting Voice.", "format": "uri", "type": "string" }, "name": { "maxLength": 100, "type": "string", "description": "Customer-facing resource name." }, "verificationAudioUrl": { "description": "Recording of the requested verification phrase from the same speaker.", "format": "uri", "type": "string" }, "verificationExtensionType": { "enum": [ "mp3", "wav", "m4a", "flac", "ogg" ], "type": "string", "description": "Verification recording extension hint." }, "verificationPhraseTaskId": { "minLength": 1, "type": "string", "description": "Completed verification-phrase Task identifier." }, "voiceAudioUrl": { "description": "Clean singing recording URL used to create the public Voice.", "format": "uri", "type": "string" }, "voiceExtensionType": { "enum": [ "mp3", "wav", "m4a", "flac", "ogg" ], "type": "string", "description": "Voice recording extension hint." } }, "required": [ "voiceAudioUrl", "verificationAudioUrl", "verificationPhraseTaskId" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "description": { "maxLength": 2000, "type": "string", "description": "Optional customer-facing resource description." }, "imageUrl": { "description": "Optional public image URL for the resulting Voice.", "format": "uri", "type": "string" }, "name": { "maxLength": 100, "type": "string", "description": "Customer-facing resource name." }, "verificationAudioUrl": { "description": "Recording of the requested verification phrase from the same speaker.", "format": "uri", "type": "string" }, "verificationExtensionType": { "enum": [ "mp3", "wav", "m4a", "flac", "ogg" ], "type": "string", "description": "Verification recording extension hint." }, "verificationPhraseTaskId": { "minLength": 1, "type": "string", "description": "Completed verification-phrase Task identifier." }, "voiceAudioUrl": { "description": "Clean singing recording URL used to create the public Voice.", "format": "uri", "type": "string" }, "voiceExtensionType": { "enum": [ "mp3", "wav", "m4a", "flac", "ogg" ], "type": "string", "description": "Voice recording extension hint." } }, "required": [ "voiceAudioUrl", "verificationAudioUrl", "verificationPhraseTaskId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsRequired": { "minimum": 0, "type": "number" }, "estimatedCompletionTime": { "anyOf": [ { "description": "Estimated completion time as an RFC 3339 string.", "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "links": { "additionalProperties": false, "properties": { "final": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "resource": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "task": { "type": "string" } }, "required": [ "task", "resource", "final" ], "type": "object" }, "pricing": { "additionalProperties": false, "properties": { "adjustmentCredits": { "description": "chargedCredits - baseCredits", "type": "number" }, "baseCredits": { "description": "Standard quoted credits before customer pricing adjustment", "type": "number" }, "billingIncrementCredits": { "description": "Smallest customer charge increment", "minimum": 0.0001, "type": "number" }, "calculatedCredits": { "description": "Precise whole-order subtotal before settlement rounding", "type": "number" }, "chargedCredits": { "description": "Credits charged for this create request", "minimum": 0, "type": "number" }, "quoteVersion": { "description": "Pricing quote version stored with the task", "type": "number" }, "settlementPolicyVersion": { "description": "Versioned customer settlement policy", "type": "string" }, "settlementRoundingCredits": { "description": "Whole-order rounding adjustment added at settlement", "minimum": 0, "type": "number" }, "source": { "enum": [ "standard", "customer_rule" ], "type": "string" } }, "required": [ "baseCredits", "chargedCredits", "adjustmentCredits", "source", "quoteVersion" ], "type": "object" }, "product": { "additionalProperties": false, "properties": { "autoFinalize": { "description": "Whether the product should finalize automatically", "type": "boolean" }, "deliveryStatus": { "anyOf": [ { "description": "Product-level delivery status when applicable", "type": "string" }, { "type": "null" } ], "nullable": true }, "featureCode": { "description": "Resolved feature code", "type": "string" }, "modelCode": { "description": "Resolved model code", "type": "string" }, "providerCode": { "description": "Resolved provider code", "type": "string" }, "resourceId": { "anyOf": [ { "description": "Product resource id when created synchronously", "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "description": "Product family for this task, e.g. suno, producer, mv", "type": "string" } }, "required": [ "type", "providerCode", "modelCode", "featureCode", "resourceId" ], "type": "object" }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "type": "string" }, "warningCodes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "taskId", "status", "creditsRequired", "requestId", "links", "pricing", "product", "warningCodes" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "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." }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 409" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 422" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "Create Voice", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/suno/voices/from-clip": { "post": { "description": "Creates a reusable public Voice from a completed clip owned by the caller. This clip-derived workflow does not require a verification phrase or real-person recordings.", "operationId": "postApiV1SunoVoicesFrom_clip", "parameters": [ { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "clipId": { "description": "Completed Suno clip owned by the current OmnAPI user.", "minLength": 1, "type": "string" }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "description": { "maxLength": 2000, "type": "string", "description": "Optional customer-facing resource description." }, "imageUrl": { "description": "Optional public image URL for the Voice.", "format": "uri", "type": "string" }, "name": { "maxLength": 100, "type": "string", "description": "Customer-facing resource name." }, "vocalRange": { "additionalProperties": false, "description": "Optional source-clip vocal range. When omitted, OmnAPI selects a continuous singing segment from the effective clip's final lyrics timeline. If a reliable timeline is unavailable, provide this range manually.", "properties": { "endSeconds": { "exclusiveMinimum": 0, "type": "number", "description": "End of the selected vocal range in seconds." }, "startSeconds": { "minimum": 0, "type": "number", "description": "Start of the selected vocal range in seconds." } }, "required": [ "startSeconds", "endSeconds" ], "type": "object" } }, "required": [ "clipId" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "clipId": { "description": "Completed Suno clip owned by the current OmnAPI user.", "minLength": 1, "type": "string" }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "description": { "maxLength": 2000, "type": "string", "description": "Optional customer-facing resource description." }, "imageUrl": { "description": "Optional public image URL for the Voice.", "format": "uri", "type": "string" }, "name": { "maxLength": 100, "type": "string", "description": "Customer-facing resource name." }, "vocalRange": { "additionalProperties": false, "description": "Optional source-clip vocal range. When omitted, OmnAPI selects a continuous singing segment from the effective clip's final lyrics timeline. If a reliable timeline is unavailable, provide this range manually.", "properties": { "endSeconds": { "exclusiveMinimum": 0, "type": "number", "description": "End of the selected vocal range in seconds." }, "startSeconds": { "minimum": 0, "type": "number", "description": "Start of the selected vocal range in seconds." } }, "required": [ "startSeconds", "endSeconds" ], "type": "object" } }, "required": [ "clipId" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "clipId": { "description": "Completed Suno clip owned by the current OmnAPI user.", "minLength": 1, "type": "string" }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "description": { "maxLength": 2000, "type": "string", "description": "Optional customer-facing resource description." }, "imageUrl": { "description": "Optional public image URL for the Voice.", "format": "uri", "type": "string" }, "name": { "maxLength": 100, "type": "string", "description": "Customer-facing resource name." }, "vocalRange": { "additionalProperties": false, "description": "Optional source-clip vocal range. When omitted, OmnAPI selects a continuous singing segment from the effective clip's final lyrics timeline. If a reliable timeline is unavailable, provide this range manually.", "properties": { "endSeconds": { "exclusiveMinimum": 0, "type": "number", "description": "End of the selected vocal range in seconds." }, "startSeconds": { "minimum": 0, "type": "number", "description": "Start of the selected vocal range in seconds." } }, "required": [ "startSeconds", "endSeconds" ], "type": "object" } }, "required": [ "clipId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsRequired": { "minimum": 0, "type": "number" }, "estimatedCompletionTime": { "anyOf": [ { "description": "Estimated completion time as an RFC 3339 string.", "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "links": { "additionalProperties": false, "properties": { "final": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "resource": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "task": { "type": "string" } }, "required": [ "task", "resource", "final" ], "type": "object" }, "pricing": { "additionalProperties": false, "properties": { "adjustmentCredits": { "description": "chargedCredits - baseCredits", "type": "number" }, "baseCredits": { "description": "Standard quoted credits before customer pricing adjustment", "type": "number" }, "billingIncrementCredits": { "description": "Smallest customer charge increment", "minimum": 0.0001, "type": "number" }, "calculatedCredits": { "description": "Precise whole-order subtotal before settlement rounding", "type": "number" }, "chargedCredits": { "description": "Credits charged for this create request", "minimum": 0, "type": "number" }, "quoteVersion": { "description": "Pricing quote version stored with the task", "type": "number" }, "settlementPolicyVersion": { "description": "Versioned customer settlement policy", "type": "string" }, "settlementRoundingCredits": { "description": "Whole-order rounding adjustment added at settlement", "minimum": 0, "type": "number" }, "source": { "enum": [ "standard", "customer_rule" ], "type": "string" } }, "required": [ "baseCredits", "chargedCredits", "adjustmentCredits", "source", "quoteVersion" ], "type": "object" }, "product": { "additionalProperties": false, "properties": { "autoFinalize": { "description": "Whether the product should finalize automatically", "type": "boolean" }, "deliveryStatus": { "anyOf": [ { "description": "Product-level delivery status when applicable", "type": "string" }, { "type": "null" } ], "nullable": true }, "featureCode": { "description": "Resolved feature code", "type": "string" }, "modelCode": { "description": "Resolved model code", "type": "string" }, "providerCode": { "description": "Resolved provider code", "type": "string" }, "resourceId": { "anyOf": [ { "description": "Product resource id when created synchronously", "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "description": "Product family for this task, e.g. suno, producer, mv", "type": "string" } }, "required": [ "type", "providerCode", "modelCode", "featureCode", "resourceId" ], "type": "object" }, "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "type": "string" }, "warningCodes": { "items": { "type": "string" }, "type": "array" } }, "required": [ "taskId", "status", "creditsRequired", "requestId", "links", "pricing", "product", "warningCodes" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "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." }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 409" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 422" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Create Voice from Clip", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/suno/voices/verification-phrase": { "get": { "description": "Returns a verification phrase and taskId for subsequent verified Voice creation. Use that taskId as verificationPhraseTaskId when creating the Voice.", "operationId": "getApiV1SunoVoicesVerification_phrase", "parameters": [ { "in": "query", "name": "language", "required": false, "schema": { "description": "Requested verification language.", "maxLength": 10, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsCharged": { "anyOf": [ { "description": "Exact credits actually charged", "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "creditsRequired": { "description": "Exact credits deducted to start the task", "minimum": 0, "type": "number" }, "errorCode": { "anyOf": [ { "description": "Error code if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "errorMessage": { "anyOf": [ { "description": "Error message if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "outputResults": { "anyOf": [ { "additionalProperties": false, "properties": { "expiresAt": { "format": "date-time", "type": "string" }, "phraseText": { "type": "string" } }, "required": [ "phraseText" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "pollUrl": { "anyOf": [ { "description": "Set only when the synchronous wait timed out (HTTP 202, status=PROCESSING). The task is still running — poll this URL for the final result. Null/absent on terminal responses.", "type": "string" }, { "type": "null" } ], "nullable": true }, "processingDuration": { "anyOf": [ { "description": "Processing duration in milliseconds", "type": "number" }, { "type": "null" } ], "nullable": true }, "processingDurationText": { "anyOf": [ { "description": "Human-readable processing duration, e.g. 16.2s", "type": "string" }, { "type": "null" } ], "nullable": true }, "resources": { "description": "Standardized resources produced by the task", "items": { "description": "A consumable resource produced by the task.", "properties": { "assetId": { "description": "Stable OmnAPI-owned asset id when available.", "type": "string" }, "assetStatus": { "enum": [ "READY", "EXPIRED", "DELETING", "DELETED" ], "type": "string" }, "byteLength": { "anyOf": [ { "description": "Resource size in bytes.", "type": "number" }, { "type": "null" } ], "nullable": true }, "content": { "anyOf": [ { "description": "Inline text content (e.g. lyrics).", "type": "string" }, { "type": "null" } ], "nullable": true }, "contentType": { "anyOf": [ { "description": "Resource content type.", "type": "string" }, { "type": "null" } ], "nullable": true }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "durationSec": { "anyOf": [ { "description": "Resource duration in seconds.", "type": "number" }, { "type": "null" } ], "nullable": true }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "id": { "description": "Stable resource id (OmnAPI resource id).", "type": "string" }, "index": { "description": "Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.", "minimum": 0, "type": "number" }, "metadata": { "anyOf": [ { "patternProperties": { "^(.*)$": {} }, "type": "object" }, { "type": "null" } ], "nullable": true }, "retainedUntil": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "role": { "enum": [ "candidate", "final", "stem", "fallback", "output" ], "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "enum": [ "MUSIC", "IMAGE", "VIDEO", "AUDIO", "TEXT", "METADATA" ], "type": "string" }, "url": { "anyOf": [ { "description": "Presigned/public URL.", "type": "string" }, { "type": "null" } ], "nullable": true }, "urlExpiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true } }, "required": [ "id", "index", "role", "type" ], "type": "object" }, "type": "array" }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "description": "Task unique identifier", "type": "string" } }, "required": [ "taskId", "status", "creditsRequired", "creditsCharged", "outputResults", "errorCode", "errorMessage", "processingDuration", "processingDurationText" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsCharged": { "anyOf": [ { "description": "Exact credits actually charged", "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "creditsRequired": { "description": "Exact credits deducted to start the task", "minimum": 0, "type": "number" }, "errorCode": { "anyOf": [ { "description": "Error code if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "errorMessage": { "anyOf": [ { "description": "Error message if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "outputResults": { "anyOf": [ { "additionalProperties": false, "properties": { "expiresAt": { "format": "date-time", "type": "string" }, "phraseText": { "type": "string" } }, "required": [ "phraseText" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "pollUrl": { "anyOf": [ { "description": "Set only when the synchronous wait timed out (HTTP 202, status=PROCESSING). The task is still running — poll this URL for the final result. Null/absent on terminal responses.", "type": "string" }, { "type": "null" } ], "nullable": true }, "processingDuration": { "anyOf": [ { "description": "Processing duration in milliseconds", "type": "number" }, { "type": "null" } ], "nullable": true }, "processingDurationText": { "anyOf": [ { "description": "Human-readable processing duration, e.g. 16.2s", "type": "string" }, { "type": "null" } ], "nullable": true }, "resources": { "description": "Standardized resources produced by the task", "items": { "description": "A consumable resource produced by the task.", "properties": { "assetId": { "description": "Stable OmnAPI-owned asset id when available.", "type": "string" }, "assetStatus": { "enum": [ "READY", "EXPIRED", "DELETING", "DELETED" ], "type": "string" }, "byteLength": { "anyOf": [ { "description": "Resource size in bytes.", "type": "number" }, { "type": "null" } ], "nullable": true }, "content": { "anyOf": [ { "description": "Inline text content (e.g. lyrics).", "type": "string" }, { "type": "null" } ], "nullable": true }, "contentType": { "anyOf": [ { "description": "Resource content type.", "type": "string" }, { "type": "null" } ], "nullable": true }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "durationSec": { "anyOf": [ { "description": "Resource duration in seconds.", "type": "number" }, { "type": "null" } ], "nullable": true }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "id": { "description": "Stable resource id (OmnAPI resource id).", "type": "string" }, "index": { "description": "Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.", "minimum": 0, "type": "number" }, "metadata": { "anyOf": [ { "patternProperties": { "^(.*)$": {} }, "type": "object" }, { "type": "null" } ], "nullable": true }, "retainedUntil": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "role": { "enum": [ "candidate", "final", "stem", "fallback", "output" ], "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "enum": [ "MUSIC", "IMAGE", "VIDEO", "AUDIO", "TEXT", "METADATA" ], "type": "string" }, "url": { "anyOf": [ { "description": "Presigned/public URL.", "type": "string" }, { "type": "null" } ], "nullable": true }, "urlExpiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true } }, "required": [ "id", "index", "role", "type" ], "type": "object" }, "type": "array" }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "description": "Task unique identifier", "type": "string" } }, "required": [ "taskId", "status", "creditsRequired", "creditsCharged", "outputResults", "errorCode", "errorMessage", "processingDuration", "processingDurationText" ], "type": "object" } } }, "description": "Response for status 202", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "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." }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 422" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Get Voice verification phrase", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/suno/voices/{voiceId}": { "get": { "description": "Voice detail by ID. There is no OmnAPI ownership restriction: any readable public Voice ID may be queried and then used for generation.", "operationId": "getApiV1SunoVoicesByVoiceId", "parameters": [ { "in": "path", "name": "voiceId", "required": true, "schema": { "type": "string" }, "description": "Reusable public Suno Voice identifier." } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsCharged": { "anyOf": [ { "description": "Exact credits actually charged", "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "creditsRequired": { "description": "Exact credits deducted to start the task", "minimum": 0, "type": "number" }, "errorCode": { "anyOf": [ { "description": "Error code if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "errorMessage": { "anyOf": [ { "description": "Error message if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "outputResults": { "anyOf": [ { "additionalProperties": false, "properties": { "voice": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": "string" }, "imageUrl": { "type": "string" }, "isPublic": { "type": "boolean" }, "name": { "type": "string" }, "voiceId": { "type": "string" }, "voiceType": { "type": "string" } }, "required": [ "voiceId" ], "type": "object" }, "voiceId": { "type": "string" } }, "required": [ "voiceId", "voice" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "pollUrl": { "anyOf": [ { "description": "Set only when the synchronous wait timed out (HTTP 202, status=PROCESSING). The task is still running — poll this URL for the final result. Null/absent on terminal responses.", "type": "string" }, { "type": "null" } ], "nullable": true }, "processingDuration": { "anyOf": [ { "description": "Processing duration in milliseconds", "type": "number" }, { "type": "null" } ], "nullable": true }, "processingDurationText": { "anyOf": [ { "description": "Human-readable processing duration, e.g. 16.2s", "type": "string" }, { "type": "null" } ], "nullable": true }, "resources": { "description": "Standardized resources produced by the task", "items": { "description": "A consumable resource produced by the task.", "properties": { "assetId": { "description": "Stable OmnAPI-owned asset id when available.", "type": "string" }, "assetStatus": { "enum": [ "READY", "EXPIRED", "DELETING", "DELETED" ], "type": "string" }, "byteLength": { "anyOf": [ { "description": "Resource size in bytes.", "type": "number" }, { "type": "null" } ], "nullable": true }, "content": { "anyOf": [ { "description": "Inline text content (e.g. lyrics).", "type": "string" }, { "type": "null" } ], "nullable": true }, "contentType": { "anyOf": [ { "description": "Resource content type.", "type": "string" }, { "type": "null" } ], "nullable": true }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "durationSec": { "anyOf": [ { "description": "Resource duration in seconds.", "type": "number" }, { "type": "null" } ], "nullable": true }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "id": { "description": "Stable resource id (OmnAPI resource id).", "type": "string" }, "index": { "description": "Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.", "minimum": 0, "type": "number" }, "metadata": { "anyOf": [ { "patternProperties": { "^(.*)$": {} }, "type": "object" }, { "type": "null" } ], "nullable": true }, "retainedUntil": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "role": { "enum": [ "candidate", "final", "stem", "fallback", "output" ], "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "enum": [ "MUSIC", "IMAGE", "VIDEO", "AUDIO", "TEXT", "METADATA" ], "type": "string" }, "url": { "anyOf": [ { "description": "Presigned/public URL.", "type": "string" }, { "type": "null" } ], "nullable": true }, "urlExpiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true } }, "required": [ "id", "index", "role", "type" ], "type": "object" }, "type": "array" }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "description": "Task unique identifier", "type": "string" } }, "required": [ "taskId", "status", "creditsRequired", "creditsCharged", "outputResults", "errorCode", "errorMessage", "processingDuration", "processingDurationText" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsCharged": { "anyOf": [ { "description": "Exact credits actually charged", "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "creditsRequired": { "description": "Exact credits deducted to start the task", "minimum": 0, "type": "number" }, "errorCode": { "anyOf": [ { "description": "Error code if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "errorMessage": { "anyOf": [ { "description": "Error message if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "outputResults": { "anyOf": [ { "additionalProperties": false, "properties": { "voice": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": "string" }, "imageUrl": { "type": "string" }, "isPublic": { "type": "boolean" }, "name": { "type": "string" }, "voiceId": { "type": "string" }, "voiceType": { "type": "string" } }, "required": [ "voiceId" ], "type": "object" }, "voiceId": { "type": "string" } }, "required": [ "voiceId", "voice" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "pollUrl": { "anyOf": [ { "description": "Set only when the synchronous wait timed out (HTTP 202, status=PROCESSING). The task is still running — poll this URL for the final result. Null/absent on terminal responses.", "type": "string" }, { "type": "null" } ], "nullable": true }, "processingDuration": { "anyOf": [ { "description": "Processing duration in milliseconds", "type": "number" }, { "type": "null" } ], "nullable": true }, "processingDurationText": { "anyOf": [ { "description": "Human-readable processing duration, e.g. 16.2s", "type": "string" }, { "type": "null" } ], "nullable": true }, "resources": { "description": "Standardized resources produced by the task", "items": { "description": "A consumable resource produced by the task.", "properties": { "assetId": { "description": "Stable OmnAPI-owned asset id when available.", "type": "string" }, "assetStatus": { "enum": [ "READY", "EXPIRED", "DELETING", "DELETED" ], "type": "string" }, "byteLength": { "anyOf": [ { "description": "Resource size in bytes.", "type": "number" }, { "type": "null" } ], "nullable": true }, "content": { "anyOf": [ { "description": "Inline text content (e.g. lyrics).", "type": "string" }, { "type": "null" } ], "nullable": true }, "contentType": { "anyOf": [ { "description": "Resource content type.", "type": "string" }, { "type": "null" } ], "nullable": true }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "durationSec": { "anyOf": [ { "description": "Resource duration in seconds.", "type": "number" }, { "type": "null" } ], "nullable": true }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "id": { "description": "Stable resource id (OmnAPI resource id).", "type": "string" }, "index": { "description": "Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.", "minimum": 0, "type": "number" }, "metadata": { "anyOf": [ { "patternProperties": { "^(.*)$": {} }, "type": "object" }, { "type": "null" } ], "nullable": true }, "retainedUntil": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "role": { "enum": [ "candidate", "final", "stem", "fallback", "output" ], "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "enum": [ "MUSIC", "IMAGE", "VIDEO", "AUDIO", "TEXT", "METADATA" ], "type": "string" }, "url": { "anyOf": [ { "description": "Presigned/public URL.", "type": "string" }, { "type": "null" } ], "nullable": true }, "urlExpiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true } }, "required": [ "id", "index", "role", "type" ], "type": "object" }, "type": "array" }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "description": "Task unique identifier", "type": "string" } }, "required": [ "taskId", "status", "creditsRequired", "creditsCharged", "outputResults", "errorCode", "errorMessage", "processingDuration", "processingDurationText" ], "type": "object" } } }, "description": "Response for status 202", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "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." }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 422" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Get Voice", "tags": [ "Suno" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tasks": { "get": { "description": "List the current user's tasks, optionally filtered by status / providerCode / appSlug. Keyset pagination is the default; pass `nextCursor` back as `cursor`. Legacy offset pagination requires `cursorMode=false` and is capped at offset 10000.", "operationId": "getApiV1Tasks", "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "description": "Filter by exact task lifecycle status." } }, { "in": "query", "name": "providerCode", "required": false, "schema": { "type": "string", "description": "Filter by lowercase provider code, for example producer, suno, mv, gpt, subtitles, or vidu. Historical provider codes remain queryable." } }, { "in": "query", "name": "modelCode", "required": false, "schema": { "description": "Filter by model code", "type": "string" } }, { "in": "query", "name": "featureCode", "required": false, "schema": { "description": "Filter by feature code", "type": "string" } }, { "in": "query", "name": "dateFrom", "required": false, "schema": { "description": "Filter tasks created after this ISO date", "type": "string" } }, { "in": "query", "name": "dateTo", "required": false, "schema": { "description": "Filter tasks created before this ISO date", "type": "string" } }, { "in": "query", "name": "appSlug", "required": false, "schema": { "description": "Filter by metadata.appSlug", "type": "string" } }, { "in": "query", "name": "tag", "required": false, "schema": { "description": "Filter by one task tag. Matching is case-insensitive and backed by the task_tags index.", "maxLength": 100, "minLength": 1, "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 50, "minimum": 1, "type": "number" }, "description": "Maximum number of items to return." }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "maximum": 10000, "minimum": 0, "type": "number" }, "description": "Zero-based pagination offset." }, { "in": "query", "name": "cursorMode", "required": false, "schema": { "default": true, "description": "Use keyset pagination and skip total count (default true). Set false only for bounded legacy offset pagination.", "type": "boolean" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "description": "Keyset cursor (last id from previous nextCursor)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "hasMore": { "description": "Whether there are more tasks (cursor mode)", "type": "boolean" }, "items": { "items": { "additionalProperties": false, "properties": { "createdAt": { "anyOf": [ { "description": "Task creation timestamp", "type": "Date" }, { "format": "date-time", "type": "string" }, { "format": "date", "type": "string" }, { "type": "number" } ], "description": "Task creation timestamp" }, "creditsCharged": { "anyOf": [ { "description": "Credits actually charged", "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "creditsRequired": { "description": "Credits deducted to start the task", "minimum": 0, "type": "number" }, "errorMessage": { "anyOf": [ { "description": "Error message if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "feature": { "anyOf": [ { "properties": { "code": { "description": "Feature code", "type": "string" }, "name": { "description": "Feature name", "type": "string" } }, "required": [ "name", "code" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "featureCode": { "description": "Feature code", "type": "string" }, "inputParameters": { "description": "Task input parameters" }, "metadata": { "anyOf": [ { "description": "Additional metadata" }, { "type": "null" } ], "nullable": true }, "model": { "anyOf": [ { "properties": { "code": { "description": "Model code", "type": "string" }, "name": { "description": "Model display name", "type": "string" }, "version": { "description": "Model version", "type": "string" } }, "required": [ "name", "code", "version" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "modelCode": { "description": "Model code", "type": "string" }, "pricing": { "anyOf": [ { "additionalProperties": false, "properties": { "components": { "items": { "additionalProperties": false, "properties": { "credits": { "description": "Final credits charged for this component.", "minimum": 0, "type": "number" }, "key": { "description": "Stable billing component key.", "type": "string" }, "label": { "description": "Human-readable component label.", "type": "string" } }, "required": [ "key", "label", "credits" ], "type": "object" }, "type": "array" }, "quoteVersion": { "description": "Pricing quote version stored with the task.", "minimum": 1, "type": "number" } }, "required": [ "quoteVersion", "components" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "processingCompletedAt": { "anyOf": [ { "anyOf": [ { "description": "Processing completion timestamp", "type": "Date" }, { "format": "date-time", "type": "string" }, { "format": "date", "type": "string" }, { "type": "number" } ], "description": "Processing completion timestamp" }, { "type": "null" } ], "nullable": true }, "processingDuration": { "anyOf": [ { "description": "Processing duration in milliseconds", "type": "number" }, { "type": "null" } ], "nullable": true }, "processingDurationText": { "anyOf": [ { "description": "Human-readable processing duration, e.g. 16.2s", "type": "string" }, { "type": "null" } ], "nullable": true }, "processingStartedAt": { "anyOf": [ { "anyOf": [ { "description": "Processing start timestamp", "type": "Date" }, { "format": "date-time", "type": "string" }, { "format": "date", "type": "string" }, { "type": "number" } ], "description": "Processing start timestamp" }, { "type": "null" } ], "nullable": true }, "progress": { "anyOf": [ { "description": "Task progress percentage (0-100)", "maximum": 100, "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "provider": { "anyOf": [ { "properties": { "code": { "description": "Provider code", "type": "string" }, "name": { "description": "Provider display name", "type": "string" } }, "required": [ "name", "code" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "providerCode": { "description": "Provider code", "type": "string" }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "tags": { "anyOf": [ { "description": "Structured task tags" }, { "type": "null" } ], "nullable": true }, "taskId": { "description": "Task unique identifier", "type": "string" }, "updatedAt": { "anyOf": [ { "description": "Last update timestamp", "type": "Date" }, { "format": "date-time", "type": "string" }, { "format": "date", "type": "string" }, { "type": "number" } ], "description": "Last update timestamp" } }, "required": [ "taskId", "status", "progress", "creditsRequired", "creditsCharged", "pricing", "errorMessage", "inputParameters", "tags", "metadata", "processingStartedAt", "processingCompletedAt", "processingDuration", "processingDurationText", "createdAt", "updatedAt", "provider", "model", "feature", "providerCode", "modelCode", "featureCode" ], "type": "object" }, "type": "array" }, "limit": { "description": "Page size", "minimum": 1, "type": "number" }, "nextCursor": { "anyOf": [ { "description": "Cursor for next page (cursor mode)", "type": "string" }, { "type": "null" } ], "nullable": true }, "offset": { "description": "Offset", "minimum": 0, "type": "number" }, "total": { "description": "Total number of tasks (offset mode only)", "minimum": 0, "type": "number" } }, "required": [ "items", "limit", "offset" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "List Tasks", "tags": [ "Tasks" ], "security": [ { "ApiKeyAuth": [] } ] }, "post": { "description": "Create a new AI task", "operationId": "postApiV1Tasks", "parameters": [ { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Select a model path; inputParameters must match that model feature's schema.", "discriminator": { "propertyName": "model" }, "oneOf": [ { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "additionalProperties": false, "properties": { "durationSec": { "description": "Target duration in seconds.", "maximum": 480, "minimum": 30, "type": "number" }, "explicit": { "type": "boolean", "description": "Whether explicit language is allowed." }, "extraGuidance": { "maxLength": 2000, "type": "string", "description": "Additional creative guidance and constraints." }, "genre": { "maxLength": 200, "type": "string", "description": "Requested musical genre direction." }, "language": { "description": "Primary lyric language. Use 'auto' to let the model decide.", "maxLength": 80, "type": "string" }, "languages": { "items": { "description": "Additional languages to consider for multilingual lyrics.", "maxLength": 80, "type": "string" }, "type": "array", "description": "Additional languages to include or consider." }, "maxTokens": { "description": "Maximum completion tokens for lyrics generation.", "maximum": 4000, "minimum": 500, "type": "number" }, "model": { "description": "Optional lyrics model override. Defaults to the configured lyrics model.", "maxLength": 120, "type": "string" }, "mood": { "maxLength": 200, "type": "string", "description": "Requested musical or visual mood." }, "multilingualMode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "sectioned", "type": "string" }, { "const": "blended", "type": "string" }, { "const": "call_and_response", "type": "string" } ], "description": "How multiple languages should be mixed." }, "negativeConstraints": { "items": { "maxLength": 80, "type": "string" }, "type": "array", "description": "Topics, styles, or tropes the output should avoid." }, "perspective": { "anyOf": [ { "const": "first_person", "type": "string" }, { "const": "second_person", "type": "string" }, { "const": "third_person", "type": "string" }, { "const": "mixed", "type": "string" } ], "description": "Requested lyric narrative perspective." }, "prompt": { "description": "Core song brief, story, scene, or hook idea.", "maxLength": 2000, "type": "string" }, "structure": { "items": { "maxLength": 50, "type": "string" }, "type": "array", "description": "Requested lyric section order." }, "temperature": { "description": "Sampling temperature for lyrics generation.", "maximum": 2, "minimum": 0, "type": "number" }, "themeKeywords": { "items": { "maxLength": 60, "type": "string" }, "type": "array", "description": "Short theme anchors for structured lyrics." }, "vocalStyle": { "maxLength": 200, "type": "string", "description": "Requested vocal performance direction." } }, "required": [ "prompt" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "gpt/gpt-4.1-mini/lyrics-generation", "gpt/gpt-4.1/lyrics-generation", "gpt/gpt-4o-mini/lyrics-generation", "gpt/gpt-4o/lyrics-generation" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "anyOf": [ { "additionalProperties": false, "properties": { "aspectRatio": { "anyOf": [ { "const": "16:9", "type": "string" }, { "const": "9:16", "type": "string" }, { "const": "1:1", "type": "string" }, { "const": "4:3", "type": "string" }, { "const": "3:4", "type": "string" } ], "description": "Requested output aspect ratio." }, "characterImage": { "minLength": 1, "type": "string", "description": "Public character reference image URL." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "generation": { "additionalProperties": false, "properties": { "creativeMode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "lyrics_story", "type": "string" }, { "const": "prompt_story", "type": "string" }, { "const": "mood_visual", "type": "string" }, { "const": "performance", "type": "string" } ], "description": "Creative intent used by Fast MV prompt and reference planning." }, "lipReferenceImages": { "description": "Ordered Premium V2 singer portrait URLs; the first item maps to the first singer.", "items": { "minLength": 1, "type": "string" }, "maxItems": 2, "minItems": 1, "type": "array" }, "managedVersion": { "anyOf": [ { "const": "oneclick-v1", "type": "string" }, { "const": "premium-v2", "type": "string" } ], "description": "Managed Fast MV engine version. Existing clients default to oneclick-v1; premium-v2 must be selected explicitly." }, "motionPreset": { "anyOf": [ { "const": "stable_performance", "type": "string" }, { "const": "cinematic_light", "type": "string" }, { "const": "dynamic_dance", "type": "string" }, { "const": "lip_sync_closeup", "type": "string" } ], "description": "Fast MV motion prompt policy." }, "performanceMode": { "anyOf": [ { "const": "sing", "type": "string" }, { "const": "sing_perform", "type": "string" }, { "const": "perform", "type": "string" }, { "const": "dance", "type": "string" } ], "description": "Premium V2 performance mode: singing, singing with performance, instrumental performance, or dance." }, "promptMode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "verbatim", "type": "string" }, { "const": "creative_brief", "type": "string" } ], "description": "Whether Fast MV preserves or compiles the caller prompt." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "high", "type": "string" } ], "description": "Requested public quality tier." }, "referenceStrategy": { "anyOf": [ { "const": "direct", "type": "string" }, { "const": "synthesize", "type": "string" } ], "description": "Fast MV policy for direct or synthesized references." }, "style": { "maxLength": 200, "type": "string", "description": "Requested creative style direction." }, "subtitleMode": { "anyOf": [ { "const": "vidu", "type": "string" }, { "const": "custom", "type": "string" } ], "description": "Fast MV subtitle rendering mode." }, "visualBoard": { "additionalProperties": false, "properties": { "imageProvider": { "anyOf": [ { "const": "gpt-image-2", "type": "string" }, { "const": "p-image", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public image-generation option code." }, "preset": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "speed", "type": "string" }, { "const": "detail", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Visual Board speed/detail policy." } }, "type": "object", "description": "Fast MV Visual Board configuration." } }, "type": "object", "description": "Product-specific generation controls." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "lipSync": { "type": "boolean", "description": "Whether the MV should use the supported lip-sync workflow." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "fast", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "preflightId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Reusable MV preflight snapshot identifier." }, "prompt": { "maxLength": 3000, "type": "string", "description": "Primary creative or operation instruction." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "referenceImages": { "items": { "minLength": 1, "type": "string" }, "maxItems": 7, "type": "array", "description": "Public reference image URLs." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "source": { "anyOf": [ { "additionalProperties": false, "properties": { "clipId": { "minLength": 1, "type": "string", "description": "Source clip identifier." }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "suno", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "clipId" ], "type": "object" }, { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "description": "Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.", "exclusiveMinimum": 0, "type": "number" }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object" } ], "description": "Public source media or product reference." }, "srtUrl": { "minLength": 1, "type": "string", "description": "Public URL of caller-supplied SRT subtitles." }, "subtitle": { "additionalProperties": false, "properties": { "fallback": { "anyOf": [ { "const": "fail", "type": "string" }, { "const": "continue_without_subtitles", "type": "string" } ], "description": "Behavior when the preferred subtitle path cannot complete." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." }, "mode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "provided", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Operation or product mode discriminator for this schema variant." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "premium", "type": "string" } ], "description": "Requested public quality tier." }, "required": { "type": "boolean", "description": "Whether the selected subtitle policy must succeed." } }, "type": "object", "description": "MV subtitle generation and fallback policy." }, "subtitleColor": { "maxLength": 20, "type": "string", "description": "Requested subtitle foreground color." }, "subtitles": { "type": "boolean", "description": "Whether subtitles are enabled for the MV." }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "mode", "source" ], "type": "object" }, { "additionalProperties": false, "properties": { "aspectRatio": { "anyOf": [ { "const": "16:9", "type": "string" }, { "const": "9:16", "type": "string" }, { "const": "1:1", "type": "string" }, { "const": "4:3", "type": "string" }, { "const": "3:4", "type": "string" } ], "description": "Requested output aspect ratio." }, "characterImage": { "minLength": 1, "type": "string", "description": "Public character reference image URL." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "generation": { "additionalProperties": false, "properties": { "imageProvider": { "anyOf": [ { "const": "p-image", "type": "string" }, { "const": "gpt-image-2", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public image-generation option code." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoProvider": { "anyOf": [ { "const": "p-video", "type": "string" }, { "const": "hailuo", "type": "string" }, { "const": "vidu", "type": "string" } ], "description": "Public scene-video option code." } }, "type": "object", "description": "Product-specific generation controls." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "lipSync": { "type": "boolean", "description": "Whether the MV should use the supported lip-sync workflow." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "preflightId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Reusable MV preflight snapshot identifier." }, "prompt": { "maxLength": 3000, "type": "string", "description": "Primary creative or operation instruction." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "referenceImages": { "items": { "minLength": 1, "type": "string" }, "maxItems": 7, "type": "array", "description": "Public reference image URLs." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "source": { "anyOf": [ { "additionalProperties": false, "properties": { "clipId": { "minLength": 1, "type": "string", "description": "Source clip identifier." }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "suno", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "clipId" ], "type": "object" }, { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "description": "Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.", "exclusiveMinimum": 0, "type": "number" }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object" } ], "description": "Public source media or product reference." }, "srtUrl": { "minLength": 1, "type": "string", "description": "Public URL of caller-supplied SRT subtitles." }, "subtitle": { "additionalProperties": false, "properties": { "fallback": { "anyOf": [ { "const": "fail", "type": "string" }, { "const": "continue_without_subtitles", "type": "string" } ], "description": "Behavior when the preferred subtitle path cannot complete." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." }, "mode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "provided", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Operation or product mode discriminator for this schema variant." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "premium", "type": "string" } ], "description": "Requested public quality tier." }, "required": { "type": "boolean", "description": "Whether the selected subtitle policy must succeed." } }, "type": "object", "description": "MV subtitle generation and fallback policy." }, "subtitleColor": { "maxLength": 20, "type": "string", "description": "Requested subtitle foreground color." }, "subtitles": { "type": "boolean", "description": "Whether subtitles are enabled for the MV." }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "mode", "source" ], "type": "object" } ], "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "mv/mv-managed-basic/generate-managed-mv" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "height": { "default": 1024, "maximum": 2048, "minimum": 256, "type": "number", "description": "Requested image height in pixels for this model branch." }, "prompt": { "description": "Image generation prompt", "maxLength": 2000, "type": "string" }, "style": { "maxLength": 100, "type": "string", "description": "Requested creative style direction." }, "width": { "default": 1024, "maximum": 2048, "minimum": 256, "type": "number", "description": "Requested image width in pixels for this model branch." } }, "required": [ "prompt" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "producer/lyria-3-5/generate-image", "producer/lyria-3-preview/generate-image", "producer/lyria-3-pro/generate-image" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "numVerses": { "maximum": 10, "minimum": 1, "type": "number", "description": "Requested number of lyric verses." }, "prompt": { "description": "Text prompt for lyrics generation", "maxLength": 3000, "type": "string" }, "style": { "maxLength": 200, "type": "string", "description": "Requested creative style direction." } }, "required": [ "prompt" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "producer/lyria-3-5/generate-lyrics", "producer/lyria-3-preview/generate-lyrics", "producer/lyria-3-pro/generate-lyrics" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "advancedMode": { "default": false, "deprecated": true, "description": "Deprecated compatibility field; Producer compose ignores this value.", "type": "boolean" }, "bpm": { "description": "Optional BPM hint", "maximum": 999, "minimum": 1, "type": "number" }, "conversationId": { "type": "string", "description": "Existing Producer conversation identifier to continue." }, "currentSongId": { "description": "Optional current song id used for queue/context continuity", "type": "string" }, "imageId": { "description": "Optional cover image id", "type": "string" }, "imagePrompt": { "description": "Optional prompt for generating a cover image", "maxLength": 1000, "type": "string" }, "instrumental": { "default": false, "description": "Whether to force instrumental generation", "type": "boolean" }, "length": { "description": "Optional length hint in seconds. Lyria 3.5 requires 60-180 seconds; Lyria 3 Pro accepts shorter values.", "maximum": 180, "minimum": 1, "type": "number" }, "lyrics": { "description": "Optional lyrics text for compose generation. If omitted while instrumental=false, OmnAPI auto-generates lyrics before compose.", "maxLength": 3000, "type": "string" }, "lyricsId": { "description": "Optional existing lyrics id", "type": "string" }, "model": { "anyOf": [ { "const": "Lyria 3.5", "type": "string" }, { "const": "Lyria 3 Pro", "type": "string" }, { "const": "Lyria 3 preview", "deprecated": true, "type": "string" } ], "description": "Producer music model. 'Lyria 3 preview' is accepted as a deprecated alias for Lyria 3.5." }, "seed": { "description": "Optional seed value", "minimum": 0, "type": "number" }, "soundPrompt": { "description": "Sound prompt for music generation", "maxLength": 500, "type": "string" }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "soundPrompt" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "producer/lyria-3-5/generate-music-compose", "producer/lyria-3-preview/generate-music-compose", "producer/lyria-3-pro/generate-music-compose" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "clipId": { "description": "Source clip id to modify", "type": "string" }, "conversationId": { "description": "Optional existing conversation id to reuse", "type": "string" }, "cropEndAt": { "deprecated": true, "description": "Deprecated alias for extendFromSeconds", "minimum": 0, "type": "number" }, "currentSongId": { "description": "Optional current song id for client_context; defaults to clipId", "type": "string" }, "extendFromSeconds": { "description": "Source timestamp where extension begins", "minimum": 0, "type": "number" }, "extendSeconds": { "default": 60, "description": "Seconds generated by ExtendSection", "exclusiveMinimum": 0, "maximum": 180, "type": "number" }, "imageId": { "description": "Optional output cover image id", "type": "string" }, "lyrics": { "description": "New lyrics (useful for cover / swap_vocals)", "maxLength": 3000, "type": "string" }, "lyricsId": { "description": "Optional lyrics id paired with lyrics when using conversation-based modify flows", "type": "string" }, "modifyMode": { "anyOf": [ { "const": "task", "type": "string" }, { "const": "conversation", "type": "string" } ], "description": "Modify transport: 'task' uses Recipe + audio__render_edit; 'conversation' lets Producer interpret a legacy/agentic request first." }, "prompt": { "description": "Additional modification instructions", "maxLength": 1000, "type": "string" }, "regions": { "description": "Ordered, non-overlapping regions for ReplaceSection", "items": { "additionalProperties": false, "properties": { "end": { "description": "Region end timestamp in seconds", "exclusiveMinimum": 0, "type": "number" }, "start": { "description": "Region start timestamp in seconds", "minimum": 0, "type": "number" } }, "required": [ "start", "end" ], "type": "object" }, "minItems": 1, "type": "array" }, "replaceEndAt": { "deprecated": true, "description": "Deprecated single-region alias for regions[].end", "minimum": 0, "type": "number" }, "replaceStartAt": { "deprecated": true, "description": "Deprecated single-region alias for regions[].start", "minimum": 0, "type": "number" }, "seed": { "description": "Optional deterministic seed for the modification", "minimum": 0, "type": "number" }, "soundPrompt": { "description": "New sound prompt (useful for swap_sound)", "maxLength": 500, "type": "string" }, "strength": { "default": 0.5, "description": "Cover similarity strength (0-1)", "maximum": 1, "minimum": 0, "type": "number" }, "tags": { "description": "Style tags for the modified clip", "maxLength": 300, "type": "string" }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." }, "transform": { "anyOf": [ { "const": "extend", "type": "string" }, { "const": "cover", "type": "string" }, { "const": "replace", "type": "string" }, { "const": "inpaint", "deprecated": true, "type": "string" }, { "const": "swap_vocals", "deprecated": true, "type": "string" }, { "const": "swap_sound", "deprecated": true, "type": "string" } ], "description": "Current deterministic edit type. inpaint is a deprecated alias for replace; swap_* use the legacy conversation path." } }, "required": [ "clipId", "transform" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "producer/lyria-3-5/generate-music-modify", "producer/lyria-3-preview/generate-music-modify", "producer/lyria-3-pro/generate-music-modify" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "clipId": { "description": "Clip ID to analyze", "type": "string" } }, "required": [ "clipId" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "suno/chirp-auk-turbo/get-audio-analysis", "suno/chirp-auk/get-audio-analysis", "suno/chirp-bluejay/get-audio-analysis", "suno/chirp-crow/get-audio-analysis", "suno/chirp-fenix/get-audio-analysis", "suno/chirp-goose/get-audio-analysis", "suno/chirp-hawk-wild/get-audio-analysis", "suno/chirp-hawk/get-audio-analysis", "suno/chirp-v4/get-audio-analysis", "suno/chirp_auk/get-audio-analysis", "suno/chirp_auk_turbo/get-audio-analysis", "suno/chirp_bluejay/get-audio-analysis", "suno/chirp_crow/get-audio-analysis", "suno/chirp_fenix/get-audio-analysis", "suno/chirp_v4/get-audio-analysis" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "clipId": { "description": "Clip ID to fetch detail for", "type": "string" } }, "required": [ "clipId" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "suno/chirp-auk-turbo/get-clip-detail", "suno/chirp-auk/get-clip-detail", "suno/chirp-bluejay/get-clip-detail", "suno/chirp-crow/get-clip-detail", "suno/chirp-fenix/get-clip-detail", "suno/chirp-goose/get-clip-detail", "suno/chirp-hawk-wild/get-clip-detail", "suno/chirp-hawk/get-clip-detail", "suno/chirp-v4/get-clip-detail", "suno/chirp_auk/get-clip-detail", "suno/chirp_auk_turbo/get-clip-detail", "suno/chirp_bluejay/get-clip-detail", "suno/chirp_crow/get-clip-detail", "suno/chirp_fenix/get-clip-detail", "suno/chirp_v4/get-clip-detail" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "clipId": { "description": "Clip ID to get lyrics timeline for", "type": "string" } }, "required": [ "clipId" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "suno/chirp-auk-turbo/get-lyrics-timeline", "suno/chirp-auk/get-lyrics-timeline", "suno/chirp-bluejay/get-lyrics-timeline", "suno/chirp-crow/get-lyrics-timeline", "suno/chirp-fenix/get-lyrics-timeline", "suno/chirp-goose/get-lyrics-timeline", "suno/chirp-hawk-wild/get-lyrics-timeline", "suno/chirp-hawk/get-lyrics-timeline", "suno/chirp-v4/get-lyrics-timeline", "suno/chirp_auk/get-lyrics-timeline", "suno/chirp_auk_turbo/get-lyrics-timeline", "suno/chirp_bluejay/get-lyrics-timeline", "suno/chirp_crow/get-lyrics-timeline", "suno/chirp_fenix/get-lyrics-timeline", "suno/chirp_v4/get-lyrics-timeline" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "voiceId": { "description": "Voice ID to fetch", "type": "string" } }, "required": [ "voiceId" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "suno/chirp-auk-turbo/get-persona", "suno/chirp-auk-turbo/get-voice", "suno/chirp-auk/get-persona", "suno/chirp-auk/get-voice", "suno/chirp-bluejay/get-persona", "suno/chirp-bluejay/get-voice", "suno/chirp-crow/get-persona", "suno/chirp-crow/get-voice", "suno/chirp-fenix/get-persona", "suno/chirp-fenix/get-voice", "suno/chirp-goose/get-persona", "suno/chirp-goose/get-voice", "suno/chirp-hawk-wild/get-persona", "suno/chirp-hawk-wild/get-voice", "suno/chirp-hawk/get-persona", "suno/chirp-hawk/get-voice", "suno/chirp-v4/get-persona", "suno/chirp-v4/get-voice", "suno/chirp_auk/get-persona", "suno/chirp_auk/get-voice", "suno/chirp_auk_turbo/get-persona", "suno/chirp_auk_turbo/get-voice", "suno/chirp_bluejay/get-persona", "suno/chirp_bluejay/get-voice", "suno/chirp_crow/get-persona", "suno/chirp_crow/get-voice", "suno/chirp_fenix/get-persona", "suno/chirp_fenix/get-voice", "suno/chirp_v4/get-persona", "suno/chirp_v4/get-voice" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "page": { "default": 1, "minimum": 1, "type": "number", "description": "One-based result page." } }, "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "suno/chirp-auk-turbo/list-personas", "suno/chirp-auk-turbo/list-voices", "suno/chirp-auk/list-personas", "suno/chirp-auk/list-voices", "suno/chirp-bluejay/list-personas", "suno/chirp-bluejay/list-voices", "suno/chirp-crow/list-personas", "suno/chirp-crow/list-voices", "suno/chirp-fenix/list-personas", "suno/chirp-fenix/list-voices", "suno/chirp-goose/list-personas", "suno/chirp-goose/list-voices", "suno/chirp-hawk-wild/list-personas", "suno/chirp-hawk-wild/list-voices", "suno/chirp-hawk/list-personas", "suno/chirp-hawk/list-voices", "suno/chirp-v4/list-personas", "suno/chirp-v4/list-voices", "suno/chirp_auk/list-personas", "suno/chirp_auk/list-voices", "suno/chirp_auk_turbo/list-personas", "suno/chirp_auk_turbo/list-voices", "suno/chirp_bluejay/list-personas", "suno/chirp_bluejay/list-voices", "suno/chirp_crow/list-personas", "suno/chirp_crow/list-voices", "suno/chirp_fenix/list-personas", "suno/chirp_fenix/list-voices", "suno/chirp_v4/list-personas", "suno/chirp_v4/list-voices" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "additionalProperties": true, "properties": { "createSessionToken": { "description": "Optional create session token", "type": "string" }, "lyricsModel": { "const": "default", "description": "Only the stable \"default\" lyrics model is supported for paired candidates", "type": "string" }, "prompt": { "description": "Text prompt for generating two lyrics candidates", "maxLength": 3000, "type": "string" }, "source": { "description": "Caller source tag retained in Task audit input", "maxLength": 100, "type": "string" } }, "required": [ "prompt" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "suno/chirp-auk-turbo/lyrics-pair", "suno/chirp-auk/lyrics-pair", "suno/chirp-bluejay/lyrics-pair", "suno/chirp-crow/lyrics-pair", "suno/chirp-fenix/lyrics-pair", "suno/chirp-goose/lyrics-pair", "suno/chirp-hawk-wild/lyrics-pair", "suno/chirp-hawk/lyrics-pair", "suno/chirp-v4/lyrics-pair", "suno/chirp_auk/lyrics-pair", "suno/chirp_auk_turbo/lyrics-pair", "suno/chirp_bluejay/lyrics-pair", "suno/chirp_crow/lyrics-pair", "suno/chirp_fenix/lyrics-pair", "suno/chirp_v4/lyrics-pair" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "mids": { "anyOf": [ { "description": "Comma-separated clip IDs", "type": "string" }, { "description": "Array of clip IDs", "items": { "type": "string" }, "type": "array" } ], "description": "Clip identifiers accepted by this model branch." }, "version": { "anyOf": [ { "const": "v2", "type": "string" }, { "const": "v3", "type": "string" } ], "description": "Requested compatibility or resource version." } }, "required": [ "mids" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "suno/chirp-auk-turbo/query-songs", "suno/chirp-auk/query-songs", "suno/chirp-bluejay/query-songs", "suno/chirp-crow/query-songs", "suno/chirp-fenix/query-songs", "suno/chirp-goose/query-songs", "suno/chirp-hawk-wild/query-songs", "suno/chirp-hawk/query-songs", "suno/chirp-v4/query-songs", "suno/chirp_auk/query-songs", "suno/chirp_auk_turbo/query-songs", "suno/chirp_bluejay/query-songs", "suno/chirp_crow/query-songs", "suno/chirp_fenix/query-songs", "suno/chirp_v4/query-songs" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "excludedStyles": { "items": { "description": "Styles to exclude from recommendations", "type": "string" }, "type": "array", "description": "Styles to exclude from the generated result." } }, "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "suno/chirp-auk-turbo/recommend-styles", "suno/chirp-auk/recommend-styles", "suno/chirp-bluejay/recommend-styles", "suno/chirp-crow/recommend-styles", "suno/chirp-fenix/recommend-styles", "suno/chirp-goose/recommend-styles", "suno/chirp-hawk-wild/recommend-styles", "suno/chirp-hawk/recommend-styles", "suno/chirp-v4/recommend-styles", "suno/chirp_auk/recommend-styles", "suno/chirp_auk_turbo/recommend-styles", "suno/chirp_bluejay/recommend-styles", "suno/chirp_crow/recommend-styles", "suno/chirp_fenix/recommend-styles", "suno/chirp_v4/recommend-styles" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "prompt": { "description": "Text prompt for lyrics generation", "maxLength": 3000, "type": "string" } }, "required": [ "prompt" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "suno/chirp-auk-turbo/text-to-lyrics", "suno/chirp-auk/text-to-lyrics", "suno/chirp-bluejay/text-to-lyrics", "suno/chirp-crow/text-to-lyrics", "suno/chirp-fenix/text-to-lyrics", "suno/chirp-goose/text-to-lyrics", "suno/chirp-hawk-wild/text-to-lyrics", "suno/chirp-hawk/text-to-lyrics", "suno/chirp-v4/text-to-lyrics", "suno/chirp_auk/text-to-lyrics", "suno/chirp_auk_turbo/text-to-lyrics", "suno/chirp_bluejay/text-to-lyrics", "suno/chirp_crow/text-to-lyrics", "suno/chirp_fenix/text-to-lyrics", "suno/chirp_v4/text-to-lyrics" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "additionalProperties": true, "properties": { "isInstrumental": { "default": false, "type": "boolean", "description": "Optional instrumental intent for the derived result." }, "prompt": { "description": "Text prompt for simple music generation (GPT description)", "maxLength": 2000, "type": "string" }, "waitAudio": { "default": true, "type": "boolean", "description": "Whether this model branch waits for playable audio before completion." } }, "required": [ "prompt" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "suno/chirp-auk-turbo/text-to-music-simple", "suno/chirp-auk/text-to-music-simple", "suno/chirp-bluejay/text-to-music-simple", "suno/chirp-crow/text-to-music-simple", "suno/chirp-fenix/text-to-music-simple", "suno/chirp-goose/text-to-music-simple", "suno/chirp-hawk-wild/text-to-music-simple", "suno/chirp-hawk/text-to-music-simple", "suno/chirp-v4/text-to-music-simple", "suno/chirp_auk/text-to-music-simple", "suno/chirp_auk_turbo/text-to-music-simple", "suno/chirp_bluejay/text-to-music-simple", "suno/chirp_crow/text-to-music-simple", "suno/chirp_fenix/text-to-music-simple", "suno/chirp_v4/text-to-music-simple" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" } ], "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "description": "Input parameters for the task", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "default": "gpt/gpt-4.1-mini/lyrics-generation", "description": "Public model path in format \"providerCode/modelCode/featureCode\". Legacy Suno model names remain accepted and execute on their V6 equivalents while retaining the requested pricing identity.", "enum": [ "gpt/gpt-4.1-mini/lyrics-generation", "gpt/gpt-4.1/lyrics-generation", "gpt/gpt-4o-mini/lyrics-generation", "gpt/gpt-4o/lyrics-generation", "mv/mv-managed-basic/generate-managed-mv", "producer/lyria-3-5/generate-image", "producer/lyria-3-5/generate-lyrics", "producer/lyria-3-5/generate-music-compose", "producer/lyria-3-5/generate-music-modify", "producer/lyria-3-preview/generate-image", "producer/lyria-3-preview/generate-lyrics", "producer/lyria-3-preview/generate-music-compose", "producer/lyria-3-preview/generate-music-modify", "producer/lyria-3-pro/generate-image", "producer/lyria-3-pro/generate-lyrics", "producer/lyria-3-pro/generate-music-compose", "producer/lyria-3-pro/generate-music-modify", "suno/chirp-auk-turbo/get-audio-analysis", "suno/chirp-auk-turbo/get-clip-detail", "suno/chirp-auk-turbo/get-lyrics-timeline", "suno/chirp-auk-turbo/get-persona", "suno/chirp-auk-turbo/get-voice", "suno/chirp-auk-turbo/list-personas", "suno/chirp-auk-turbo/list-voices", "suno/chirp-auk-turbo/lyrics-pair", "suno/chirp-auk-turbo/query-songs", "suno/chirp-auk-turbo/recommend-styles", "suno/chirp-auk-turbo/text-to-lyrics", "suno/chirp-auk-turbo/text-to-music-simple", "suno/chirp-auk/get-audio-analysis", "suno/chirp-auk/get-clip-detail", "suno/chirp-auk/get-lyrics-timeline", "suno/chirp-auk/get-persona", "suno/chirp-auk/get-voice", "suno/chirp-auk/list-personas", "suno/chirp-auk/list-voices", "suno/chirp-auk/lyrics-pair", "suno/chirp-auk/query-songs", "suno/chirp-auk/recommend-styles", "suno/chirp-auk/text-to-lyrics", "suno/chirp-auk/text-to-music-simple", "suno/chirp-bluejay/get-audio-analysis", "suno/chirp-bluejay/get-clip-detail", "suno/chirp-bluejay/get-lyrics-timeline", "suno/chirp-bluejay/get-persona", "suno/chirp-bluejay/get-voice", "suno/chirp-bluejay/list-personas", "suno/chirp-bluejay/list-voices", "suno/chirp-bluejay/lyrics-pair", "suno/chirp-bluejay/query-songs", "suno/chirp-bluejay/recommend-styles", "suno/chirp-bluejay/text-to-lyrics", "suno/chirp-bluejay/text-to-music-simple", "suno/chirp-crow/get-audio-analysis", "suno/chirp-crow/get-clip-detail", "suno/chirp-crow/get-lyrics-timeline", "suno/chirp-crow/get-persona", "suno/chirp-crow/get-voice", "suno/chirp-crow/list-personas", "suno/chirp-crow/list-voices", "suno/chirp-crow/lyrics-pair", "suno/chirp-crow/query-songs", "suno/chirp-crow/recommend-styles", "suno/chirp-crow/text-to-lyrics", "suno/chirp-crow/text-to-music-simple", "suno/chirp-fenix/get-audio-analysis", "suno/chirp-fenix/get-clip-detail", "suno/chirp-fenix/get-lyrics-timeline", "suno/chirp-fenix/get-persona", "suno/chirp-fenix/get-voice", "suno/chirp-fenix/list-personas", "suno/chirp-fenix/list-voices", "suno/chirp-fenix/lyrics-pair", "suno/chirp-fenix/query-songs", "suno/chirp-fenix/recommend-styles", "suno/chirp-fenix/text-to-lyrics", "suno/chirp-fenix/text-to-music-simple", "suno/chirp-goose/get-audio-analysis", "suno/chirp-goose/get-clip-detail", "suno/chirp-goose/get-lyrics-timeline", "suno/chirp-goose/get-persona", "suno/chirp-goose/get-voice", "suno/chirp-goose/list-personas", "suno/chirp-goose/list-voices", "suno/chirp-goose/lyrics-pair", "suno/chirp-goose/query-songs", "suno/chirp-goose/recommend-styles", "suno/chirp-goose/text-to-lyrics", "suno/chirp-goose/text-to-music-simple", "suno/chirp-hawk-wild/get-audio-analysis", "suno/chirp-hawk-wild/get-clip-detail", "suno/chirp-hawk-wild/get-lyrics-timeline", "suno/chirp-hawk-wild/get-persona", "suno/chirp-hawk-wild/get-voice", "suno/chirp-hawk-wild/list-personas", "suno/chirp-hawk-wild/list-voices", "suno/chirp-hawk-wild/lyrics-pair", "suno/chirp-hawk-wild/query-songs", "suno/chirp-hawk-wild/recommend-styles", "suno/chirp-hawk-wild/text-to-lyrics", "suno/chirp-hawk-wild/text-to-music-simple", "suno/chirp-hawk/get-audio-analysis", "suno/chirp-hawk/get-clip-detail", "suno/chirp-hawk/get-lyrics-timeline", "suno/chirp-hawk/get-persona", "suno/chirp-hawk/get-voice", "suno/chirp-hawk/list-personas", "suno/chirp-hawk/list-voices", "suno/chirp-hawk/lyrics-pair", "suno/chirp-hawk/query-songs", "suno/chirp-hawk/recommend-styles", "suno/chirp-hawk/text-to-lyrics", "suno/chirp-hawk/text-to-music-simple", "suno/chirp-v4/get-audio-analysis", "suno/chirp-v4/get-clip-detail", "suno/chirp-v4/get-lyrics-timeline", "suno/chirp-v4/get-persona", "suno/chirp-v4/get-voice", "suno/chirp-v4/list-personas", "suno/chirp-v4/list-voices", "suno/chirp-v4/lyrics-pair", "suno/chirp-v4/query-songs", "suno/chirp-v4/recommend-styles", "suno/chirp-v4/text-to-lyrics", "suno/chirp-v4/text-to-music-simple", "suno/chirp_auk/get-audio-analysis", "suno/chirp_auk/get-clip-detail", "suno/chirp_auk/get-lyrics-timeline", "suno/chirp_auk/get-persona", "suno/chirp_auk/get-voice", "suno/chirp_auk/list-personas", "suno/chirp_auk/list-voices", "suno/chirp_auk/lyrics-pair", "suno/chirp_auk/query-songs", "suno/chirp_auk/recommend-styles", "suno/chirp_auk/text-to-lyrics", "suno/chirp_auk/text-to-music-simple", "suno/chirp_auk_turbo/get-audio-analysis", "suno/chirp_auk_turbo/get-clip-detail", "suno/chirp_auk_turbo/get-lyrics-timeline", "suno/chirp_auk_turbo/get-persona", "suno/chirp_auk_turbo/get-voice", "suno/chirp_auk_turbo/list-personas", "suno/chirp_auk_turbo/list-voices", "suno/chirp_auk_turbo/lyrics-pair", "suno/chirp_auk_turbo/query-songs", "suno/chirp_auk_turbo/recommend-styles", "suno/chirp_auk_turbo/text-to-lyrics", "suno/chirp_auk_turbo/text-to-music-simple", "suno/chirp_bluejay/get-audio-analysis", "suno/chirp_bluejay/get-clip-detail", "suno/chirp_bluejay/get-lyrics-timeline", "suno/chirp_bluejay/get-persona", "suno/chirp_bluejay/get-voice", "suno/chirp_bluejay/list-personas", "suno/chirp_bluejay/list-voices", "suno/chirp_bluejay/lyrics-pair", "suno/chirp_bluejay/query-songs", "suno/chirp_bluejay/recommend-styles", "suno/chirp_bluejay/text-to-lyrics", "suno/chirp_bluejay/text-to-music-simple", "suno/chirp_crow/get-audio-analysis", "suno/chirp_crow/get-clip-detail", "suno/chirp_crow/get-lyrics-timeline", "suno/chirp_crow/get-persona", "suno/chirp_crow/get-voice", "suno/chirp_crow/list-personas", "suno/chirp_crow/list-voices", "suno/chirp_crow/lyrics-pair", "suno/chirp_crow/query-songs", "suno/chirp_crow/recommend-styles", "suno/chirp_crow/text-to-lyrics", "suno/chirp_crow/text-to-music-simple", "suno/chirp_fenix/get-audio-analysis", "suno/chirp_fenix/get-clip-detail", "suno/chirp_fenix/get-lyrics-timeline", "suno/chirp_fenix/get-persona", "suno/chirp_fenix/get-voice", "suno/chirp_fenix/list-personas", "suno/chirp_fenix/list-voices", "suno/chirp_fenix/lyrics-pair", "suno/chirp_fenix/query-songs", "suno/chirp_fenix/recommend-styles", "suno/chirp_fenix/text-to-lyrics", "suno/chirp_fenix/text-to-music-simple", "suno/chirp_v4/get-audio-analysis", "suno/chirp_v4/get-clip-detail", "suno/chirp_v4/get-lyrics-timeline", "suno/chirp_v4/get-persona", "suno/chirp_v4/get-voice", "suno/chirp_v4/list-personas", "suno/chirp_v4/list-voices", "suno/chirp_v4/lyrics-pair", "suno/chirp_v4/query-songs", "suno/chirp_v4/recommend-styles", "suno/chirp_v4/text-to-lyrics", "suno/chirp_v4/text-to-music-simple" ], "examples": [ "gpt/gpt-4.1-mini/lyrics-generation", "gpt/gpt-4.1/lyrics-generation", "gpt/gpt-4o-mini/lyrics-generation", "gpt/gpt-4o/lyrics-generation", "mv/mv-managed-basic/generate-managed-mv" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "description": "Input parameters for the task", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "default": "gpt/gpt-4.1-mini/lyrics-generation", "description": "Public model path in format \"providerCode/modelCode/featureCode\". Legacy Suno model names remain accepted and execute on their V6 equivalents while retaining the requested pricing identity.", "enum": [ "gpt/gpt-4.1-mini/lyrics-generation", "gpt/gpt-4.1/lyrics-generation", "gpt/gpt-4o-mini/lyrics-generation", "gpt/gpt-4o/lyrics-generation", "mv/mv-managed-basic/generate-managed-mv", "producer/lyria-3-5/generate-image", "producer/lyria-3-5/generate-lyrics", "producer/lyria-3-5/generate-music-compose", "producer/lyria-3-5/generate-music-modify", "producer/lyria-3-preview/generate-image", "producer/lyria-3-preview/generate-lyrics", "producer/lyria-3-preview/generate-music-compose", "producer/lyria-3-preview/generate-music-modify", "producer/lyria-3-pro/generate-image", "producer/lyria-3-pro/generate-lyrics", "producer/lyria-3-pro/generate-music-compose", "producer/lyria-3-pro/generate-music-modify", "suno/chirp-auk-turbo/get-audio-analysis", "suno/chirp-auk-turbo/get-clip-detail", "suno/chirp-auk-turbo/get-lyrics-timeline", "suno/chirp-auk-turbo/get-persona", "suno/chirp-auk-turbo/get-voice", "suno/chirp-auk-turbo/list-personas", "suno/chirp-auk-turbo/list-voices", "suno/chirp-auk-turbo/lyrics-pair", "suno/chirp-auk-turbo/query-songs", "suno/chirp-auk-turbo/recommend-styles", "suno/chirp-auk-turbo/text-to-lyrics", "suno/chirp-auk-turbo/text-to-music-simple", "suno/chirp-auk/get-audio-analysis", "suno/chirp-auk/get-clip-detail", "suno/chirp-auk/get-lyrics-timeline", "suno/chirp-auk/get-persona", "suno/chirp-auk/get-voice", "suno/chirp-auk/list-personas", "suno/chirp-auk/list-voices", "suno/chirp-auk/lyrics-pair", "suno/chirp-auk/query-songs", "suno/chirp-auk/recommend-styles", "suno/chirp-auk/text-to-lyrics", "suno/chirp-auk/text-to-music-simple", "suno/chirp-bluejay/get-audio-analysis", "suno/chirp-bluejay/get-clip-detail", "suno/chirp-bluejay/get-lyrics-timeline", "suno/chirp-bluejay/get-persona", "suno/chirp-bluejay/get-voice", "suno/chirp-bluejay/list-personas", "suno/chirp-bluejay/list-voices", "suno/chirp-bluejay/lyrics-pair", "suno/chirp-bluejay/query-songs", "suno/chirp-bluejay/recommend-styles", "suno/chirp-bluejay/text-to-lyrics", "suno/chirp-bluejay/text-to-music-simple", "suno/chirp-crow/get-audio-analysis", "suno/chirp-crow/get-clip-detail", "suno/chirp-crow/get-lyrics-timeline", "suno/chirp-crow/get-persona", "suno/chirp-crow/get-voice", "suno/chirp-crow/list-personas", "suno/chirp-crow/list-voices", "suno/chirp-crow/lyrics-pair", "suno/chirp-crow/query-songs", "suno/chirp-crow/recommend-styles", "suno/chirp-crow/text-to-lyrics", "suno/chirp-crow/text-to-music-simple", "suno/chirp-fenix/get-audio-analysis", "suno/chirp-fenix/get-clip-detail", "suno/chirp-fenix/get-lyrics-timeline", "suno/chirp-fenix/get-persona", "suno/chirp-fenix/get-voice", "suno/chirp-fenix/list-personas", "suno/chirp-fenix/list-voices", "suno/chirp-fenix/lyrics-pair", "suno/chirp-fenix/query-songs", "suno/chirp-fenix/recommend-styles", "suno/chirp-fenix/text-to-lyrics", "suno/chirp-fenix/text-to-music-simple", "suno/chirp-goose/get-audio-analysis", "suno/chirp-goose/get-clip-detail", "suno/chirp-goose/get-lyrics-timeline", "suno/chirp-goose/get-persona", "suno/chirp-goose/get-voice", "suno/chirp-goose/list-personas", "suno/chirp-goose/list-voices", "suno/chirp-goose/lyrics-pair", "suno/chirp-goose/query-songs", "suno/chirp-goose/recommend-styles", "suno/chirp-goose/text-to-lyrics", "suno/chirp-goose/text-to-music-simple", "suno/chirp-hawk-wild/get-audio-analysis", "suno/chirp-hawk-wild/get-clip-detail", "suno/chirp-hawk-wild/get-lyrics-timeline", "suno/chirp-hawk-wild/get-persona", "suno/chirp-hawk-wild/get-voice", "suno/chirp-hawk-wild/list-personas", "suno/chirp-hawk-wild/list-voices", "suno/chirp-hawk-wild/lyrics-pair", "suno/chirp-hawk-wild/query-songs", "suno/chirp-hawk-wild/recommend-styles", "suno/chirp-hawk-wild/text-to-lyrics", "suno/chirp-hawk-wild/text-to-music-simple", "suno/chirp-hawk/get-audio-analysis", "suno/chirp-hawk/get-clip-detail", "suno/chirp-hawk/get-lyrics-timeline", "suno/chirp-hawk/get-persona", "suno/chirp-hawk/get-voice", "suno/chirp-hawk/list-personas", "suno/chirp-hawk/list-voices", "suno/chirp-hawk/lyrics-pair", "suno/chirp-hawk/query-songs", "suno/chirp-hawk/recommend-styles", "suno/chirp-hawk/text-to-lyrics", "suno/chirp-hawk/text-to-music-simple", "suno/chirp-v4/get-audio-analysis", "suno/chirp-v4/get-clip-detail", "suno/chirp-v4/get-lyrics-timeline", "suno/chirp-v4/get-persona", "suno/chirp-v4/get-voice", "suno/chirp-v4/list-personas", "suno/chirp-v4/list-voices", "suno/chirp-v4/lyrics-pair", "suno/chirp-v4/query-songs", "suno/chirp-v4/recommend-styles", "suno/chirp-v4/text-to-lyrics", "suno/chirp-v4/text-to-music-simple", "suno/chirp_auk/get-audio-analysis", "suno/chirp_auk/get-clip-detail", "suno/chirp_auk/get-lyrics-timeline", "suno/chirp_auk/get-persona", "suno/chirp_auk/get-voice", "suno/chirp_auk/list-personas", "suno/chirp_auk/list-voices", "suno/chirp_auk/lyrics-pair", "suno/chirp_auk/query-songs", "suno/chirp_auk/recommend-styles", "suno/chirp_auk/text-to-lyrics", "suno/chirp_auk/text-to-music-simple", "suno/chirp_auk_turbo/get-audio-analysis", "suno/chirp_auk_turbo/get-clip-detail", "suno/chirp_auk_turbo/get-lyrics-timeline", "suno/chirp_auk_turbo/get-persona", "suno/chirp_auk_turbo/get-voice", "suno/chirp_auk_turbo/list-personas", "suno/chirp_auk_turbo/list-voices", "suno/chirp_auk_turbo/lyrics-pair", "suno/chirp_auk_turbo/query-songs", "suno/chirp_auk_turbo/recommend-styles", "suno/chirp_auk_turbo/text-to-lyrics", "suno/chirp_auk_turbo/text-to-music-simple", "suno/chirp_bluejay/get-audio-analysis", "suno/chirp_bluejay/get-clip-detail", "suno/chirp_bluejay/get-lyrics-timeline", "suno/chirp_bluejay/get-persona", "suno/chirp_bluejay/get-voice", "suno/chirp_bluejay/list-personas", "suno/chirp_bluejay/list-voices", "suno/chirp_bluejay/lyrics-pair", "suno/chirp_bluejay/query-songs", "suno/chirp_bluejay/recommend-styles", "suno/chirp_bluejay/text-to-lyrics", "suno/chirp_bluejay/text-to-music-simple", "suno/chirp_crow/get-audio-analysis", "suno/chirp_crow/get-clip-detail", "suno/chirp_crow/get-lyrics-timeline", "suno/chirp_crow/get-persona", "suno/chirp_crow/get-voice", "suno/chirp_crow/list-personas", "suno/chirp_crow/list-voices", "suno/chirp_crow/lyrics-pair", "suno/chirp_crow/query-songs", "suno/chirp_crow/recommend-styles", "suno/chirp_crow/text-to-lyrics", "suno/chirp_crow/text-to-music-simple", "suno/chirp_fenix/get-audio-analysis", "suno/chirp_fenix/get-clip-detail", "suno/chirp_fenix/get-lyrics-timeline", "suno/chirp_fenix/get-persona", "suno/chirp_fenix/get-voice", "suno/chirp_fenix/list-personas", "suno/chirp_fenix/list-voices", "suno/chirp_fenix/lyrics-pair", "suno/chirp_fenix/query-songs", "suno/chirp_fenix/recommend-styles", "suno/chirp_fenix/text-to-lyrics", "suno/chirp_fenix/text-to-music-simple", "suno/chirp_v4/get-audio-analysis", "suno/chirp_v4/get-clip-detail", "suno/chirp_v4/get-lyrics-timeline", "suno/chirp_v4/get-persona", "suno/chirp_v4/get-voice", "suno/chirp_v4/list-personas", "suno/chirp_v4/list-voices", "suno/chirp_v4/lyrics-pair", "suno/chirp_v4/query-songs", "suno/chirp_v4/recommend-styles", "suno/chirp_v4/text-to-lyrics", "suno/chirp_v4/text-to-music-simple" ], "examples": [ "gpt/gpt-4.1-mini/lyrics-generation", "gpt/gpt-4.1/lyrics-generation", "gpt/gpt-4o-mini/lyrics-generation", "gpt/gpt-4o/lyrics-generation", "mv/mv-managed-basic/generate-managed-mv" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "description": "Input parameters for the task", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "default": "gpt/gpt-4.1-mini/lyrics-generation", "description": "Public model path in format \"providerCode/modelCode/featureCode\". Legacy Suno model names remain accepted and execute on their V6 equivalents while retaining the requested pricing identity.", "enum": [ "gpt/gpt-4.1-mini/lyrics-generation", "gpt/gpt-4.1/lyrics-generation", "gpt/gpt-4o-mini/lyrics-generation", "gpt/gpt-4o/lyrics-generation", "mv/mv-managed-basic/generate-managed-mv", "producer/lyria-3-5/generate-image", "producer/lyria-3-5/generate-lyrics", "producer/lyria-3-5/generate-music-compose", "producer/lyria-3-5/generate-music-modify", "producer/lyria-3-preview/generate-image", "producer/lyria-3-preview/generate-lyrics", "producer/lyria-3-preview/generate-music-compose", "producer/lyria-3-preview/generate-music-modify", "producer/lyria-3-pro/generate-image", "producer/lyria-3-pro/generate-lyrics", "producer/lyria-3-pro/generate-music-compose", "producer/lyria-3-pro/generate-music-modify", "suno/chirp-auk-turbo/get-audio-analysis", "suno/chirp-auk-turbo/get-clip-detail", "suno/chirp-auk-turbo/get-lyrics-timeline", "suno/chirp-auk-turbo/get-persona", "suno/chirp-auk-turbo/get-voice", "suno/chirp-auk-turbo/list-personas", "suno/chirp-auk-turbo/list-voices", "suno/chirp-auk-turbo/lyrics-pair", "suno/chirp-auk-turbo/query-songs", "suno/chirp-auk-turbo/recommend-styles", "suno/chirp-auk-turbo/text-to-lyrics", "suno/chirp-auk-turbo/text-to-music-simple", "suno/chirp-auk/get-audio-analysis", "suno/chirp-auk/get-clip-detail", "suno/chirp-auk/get-lyrics-timeline", "suno/chirp-auk/get-persona", "suno/chirp-auk/get-voice", "suno/chirp-auk/list-personas", "suno/chirp-auk/list-voices", "suno/chirp-auk/lyrics-pair", "suno/chirp-auk/query-songs", "suno/chirp-auk/recommend-styles", "suno/chirp-auk/text-to-lyrics", "suno/chirp-auk/text-to-music-simple", "suno/chirp-bluejay/get-audio-analysis", "suno/chirp-bluejay/get-clip-detail", "suno/chirp-bluejay/get-lyrics-timeline", "suno/chirp-bluejay/get-persona", "suno/chirp-bluejay/get-voice", "suno/chirp-bluejay/list-personas", "suno/chirp-bluejay/list-voices", "suno/chirp-bluejay/lyrics-pair", "suno/chirp-bluejay/query-songs", "suno/chirp-bluejay/recommend-styles", "suno/chirp-bluejay/text-to-lyrics", "suno/chirp-bluejay/text-to-music-simple", "suno/chirp-crow/get-audio-analysis", "suno/chirp-crow/get-clip-detail", "suno/chirp-crow/get-lyrics-timeline", "suno/chirp-crow/get-persona", "suno/chirp-crow/get-voice", "suno/chirp-crow/list-personas", "suno/chirp-crow/list-voices", "suno/chirp-crow/lyrics-pair", "suno/chirp-crow/query-songs", "suno/chirp-crow/recommend-styles", "suno/chirp-crow/text-to-lyrics", "suno/chirp-crow/text-to-music-simple", "suno/chirp-fenix/get-audio-analysis", "suno/chirp-fenix/get-clip-detail", "suno/chirp-fenix/get-lyrics-timeline", "suno/chirp-fenix/get-persona", "suno/chirp-fenix/get-voice", "suno/chirp-fenix/list-personas", "suno/chirp-fenix/list-voices", "suno/chirp-fenix/lyrics-pair", "suno/chirp-fenix/query-songs", "suno/chirp-fenix/recommend-styles", "suno/chirp-fenix/text-to-lyrics", "suno/chirp-fenix/text-to-music-simple", "suno/chirp-goose/get-audio-analysis", "suno/chirp-goose/get-clip-detail", "suno/chirp-goose/get-lyrics-timeline", "suno/chirp-goose/get-persona", "suno/chirp-goose/get-voice", "suno/chirp-goose/list-personas", "suno/chirp-goose/list-voices", "suno/chirp-goose/lyrics-pair", "suno/chirp-goose/query-songs", "suno/chirp-goose/recommend-styles", "suno/chirp-goose/text-to-lyrics", "suno/chirp-goose/text-to-music-simple", "suno/chirp-hawk-wild/get-audio-analysis", "suno/chirp-hawk-wild/get-clip-detail", "suno/chirp-hawk-wild/get-lyrics-timeline", "suno/chirp-hawk-wild/get-persona", "suno/chirp-hawk-wild/get-voice", "suno/chirp-hawk-wild/list-personas", "suno/chirp-hawk-wild/list-voices", "suno/chirp-hawk-wild/lyrics-pair", "suno/chirp-hawk-wild/query-songs", "suno/chirp-hawk-wild/recommend-styles", "suno/chirp-hawk-wild/text-to-lyrics", "suno/chirp-hawk-wild/text-to-music-simple", "suno/chirp-hawk/get-audio-analysis", "suno/chirp-hawk/get-clip-detail", "suno/chirp-hawk/get-lyrics-timeline", "suno/chirp-hawk/get-persona", "suno/chirp-hawk/get-voice", "suno/chirp-hawk/list-personas", "suno/chirp-hawk/list-voices", "suno/chirp-hawk/lyrics-pair", "suno/chirp-hawk/query-songs", "suno/chirp-hawk/recommend-styles", "suno/chirp-hawk/text-to-lyrics", "suno/chirp-hawk/text-to-music-simple", "suno/chirp-v4/get-audio-analysis", "suno/chirp-v4/get-clip-detail", "suno/chirp-v4/get-lyrics-timeline", "suno/chirp-v4/get-persona", "suno/chirp-v4/get-voice", "suno/chirp-v4/list-personas", "suno/chirp-v4/list-voices", "suno/chirp-v4/lyrics-pair", "suno/chirp-v4/query-songs", "suno/chirp-v4/recommend-styles", "suno/chirp-v4/text-to-lyrics", "suno/chirp-v4/text-to-music-simple", "suno/chirp_auk/get-audio-analysis", "suno/chirp_auk/get-clip-detail", "suno/chirp_auk/get-lyrics-timeline", "suno/chirp_auk/get-persona", "suno/chirp_auk/get-voice", "suno/chirp_auk/list-personas", "suno/chirp_auk/list-voices", "suno/chirp_auk/lyrics-pair", "suno/chirp_auk/query-songs", "suno/chirp_auk/recommend-styles", "suno/chirp_auk/text-to-lyrics", "suno/chirp_auk/text-to-music-simple", "suno/chirp_auk_turbo/get-audio-analysis", "suno/chirp_auk_turbo/get-clip-detail", "suno/chirp_auk_turbo/get-lyrics-timeline", "suno/chirp_auk_turbo/get-persona", "suno/chirp_auk_turbo/get-voice", "suno/chirp_auk_turbo/list-personas", "suno/chirp_auk_turbo/list-voices", "suno/chirp_auk_turbo/lyrics-pair", "suno/chirp_auk_turbo/query-songs", "suno/chirp_auk_turbo/recommend-styles", "suno/chirp_auk_turbo/text-to-lyrics", "suno/chirp_auk_turbo/text-to-music-simple", "suno/chirp_bluejay/get-audio-analysis", "suno/chirp_bluejay/get-clip-detail", "suno/chirp_bluejay/get-lyrics-timeline", "suno/chirp_bluejay/get-persona", "suno/chirp_bluejay/get-voice", "suno/chirp_bluejay/list-personas", "suno/chirp_bluejay/list-voices", "suno/chirp_bluejay/lyrics-pair", "suno/chirp_bluejay/query-songs", "suno/chirp_bluejay/recommend-styles", "suno/chirp_bluejay/text-to-lyrics", "suno/chirp_bluejay/text-to-music-simple", "suno/chirp_crow/get-audio-analysis", "suno/chirp_crow/get-clip-detail", "suno/chirp_crow/get-lyrics-timeline", "suno/chirp_crow/get-persona", "suno/chirp_crow/get-voice", "suno/chirp_crow/list-personas", "suno/chirp_crow/list-voices", "suno/chirp_crow/lyrics-pair", "suno/chirp_crow/query-songs", "suno/chirp_crow/recommend-styles", "suno/chirp_crow/text-to-lyrics", "suno/chirp_crow/text-to-music-simple", "suno/chirp_fenix/get-audio-analysis", "suno/chirp_fenix/get-clip-detail", "suno/chirp_fenix/get-lyrics-timeline", "suno/chirp_fenix/get-persona", "suno/chirp_fenix/get-voice", "suno/chirp_fenix/list-personas", "suno/chirp_fenix/list-voices", "suno/chirp_fenix/lyrics-pair", "suno/chirp_fenix/query-songs", "suno/chirp_fenix/recommend-styles", "suno/chirp_fenix/text-to-lyrics", "suno/chirp_fenix/text-to-music-simple", "suno/chirp_v4/get-audio-analysis", "suno/chirp_v4/get-clip-detail", "suno/chirp_v4/get-lyrics-timeline", "suno/chirp_v4/get-persona", "suno/chirp_v4/get-voice", "suno/chirp_v4/list-personas", "suno/chirp_v4/list-voices", "suno/chirp_v4/lyrics-pair", "suno/chirp_v4/query-songs", "suno/chirp_v4/recommend-styles", "suno/chirp_v4/text-to-lyrics", "suno/chirp_v4/text-to-music-simple" ], "examples": [ "gpt/gpt-4.1-mini/lyrics-generation", "gpt/gpt-4.1/lyrics-generation", "gpt/gpt-4o-mini/lyrics-generation", "gpt/gpt-4o/lyrics-generation", "mv/mv-managed-basic/generate-managed-mv" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsRequired": { "description": "Exact credits deducted to start the task", "minimum": 0, "type": "number" }, "estimatedCompletionTime": { "anyOf": [ { "anyOf": [ { "description": "Estimated completion time", "type": "Date" }, { "format": "date-time", "type": "string" }, { "format": "date", "type": "string" }, { "type": "number" } ], "description": "Estimated completion time" }, { "type": "null" } ], "nullable": true }, "links": { "additionalProperties": false, "properties": { "final": { "anyOf": [ { "description": "Final downloadable resource URL when available", "type": "string" }, { "type": "null" } ], "nullable": true }, "resource": { "anyOf": [ { "description": "Product resource URL when the product has a dedicated view endpoint", "type": "string" }, { "type": "null" } ], "nullable": true }, "stream": { "description": "Task SSE stream URL for the created task", "type": "string" }, "task": { "description": "Task polling URL for the created task", "type": "string" } }, "required": [ "task", "stream", "resource", "final" ], "type": "object" }, "pricing": { "additionalProperties": false, "properties": { "adjustmentCredits": { "description": "chargedCredits - baseCredits", "type": "number" }, "baseCredits": { "description": "Standard quoted credits before customer pricing adjustment", "type": "number" }, "billingIncrementCredits": { "description": "Smallest customer charge increment", "minimum": 0.0001, "type": "number" }, "calculatedCredits": { "description": "Precise whole-order subtotal before settlement rounding", "type": "number" }, "chargedCredits": { "description": "Credits charged for this create request", "minimum": 0, "type": "number" }, "quoteVersion": { "description": "Pricing quote version stored with the task", "type": "number" }, "settlementPolicyVersion": { "description": "Versioned customer settlement policy", "type": "string" }, "settlementRoundingCredits": { "description": "Whole-order rounding adjustment added at settlement", "minimum": 0, "type": "number" }, "source": { "enum": [ "standard", "customer_rule" ], "type": "string" } }, "required": [ "baseCredits", "chargedCredits", "adjustmentCredits", "source", "quoteVersion" ], "type": "object" }, "product": { "additionalProperties": false, "properties": { "autoFinalize": { "description": "Whether the product should finalize automatically", "type": "boolean" }, "deliveryStatus": { "anyOf": [ { "description": "Product-level delivery status when applicable", "type": "string" }, { "type": "null" } ], "nullable": true }, "featureCode": { "description": "Resolved feature code", "type": "string" }, "modelCode": { "description": "Resolved model code", "type": "string" }, "providerCode": { "description": "Resolved provider code", "type": "string" }, "resourceId": { "anyOf": [ { "description": "Product resource id when created synchronously", "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "description": "Product family for this task, e.g. suno, producer, mv", "type": "string" } }, "required": [ "type", "providerCode", "modelCode", "featureCode", "resourceId" ], "type": "object" }, "requestId": { "anyOf": [ { "description": "Request id echoed from X-Request-Id or generated by API", "type": "string" }, { "type": "null" } ], "nullable": true }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "description": "Task unique identifier", "type": "string" }, "warningCodes": { "items": { "description": "Non-fatal request warnings", "type": "string" }, "type": "array" } }, "required": [ "taskId", "status", "creditsRequired", "requestId", "links", "pricing", "product", "warningCodes" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403 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." }, "408": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 408" }, "413": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 413" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 422" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 502" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Create Task", "tags": [ "Tasks" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tasks/sync": { "post": { "description": "Create a task and wait for result. Returns 200 on terminal status (COMPLETED/FAILED/CANCELLED) and 202 when the wait timed out — clients should poll GET /api/v1/tasks/{taskId} in that case.", "operationId": "postApiV1TasksSync", "parameters": [ { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Select a model path; inputParameters must match that model feature's schema.", "discriminator": { "propertyName": "model" }, "oneOf": [ { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "additionalProperties": false, "properties": { "durationSec": { "description": "Target duration in seconds.", "maximum": 480, "minimum": 30, "type": "number" }, "explicit": { "type": "boolean", "description": "Whether explicit language is allowed." }, "extraGuidance": { "maxLength": 2000, "type": "string", "description": "Additional creative guidance and constraints." }, "genre": { "maxLength": 200, "type": "string", "description": "Requested musical genre direction." }, "language": { "description": "Primary lyric language. Use 'auto' to let the model decide.", "maxLength": 80, "type": "string" }, "languages": { "items": { "description": "Additional languages to consider for multilingual lyrics.", "maxLength": 80, "type": "string" }, "type": "array", "description": "Additional languages to include or consider." }, "maxTokens": { "description": "Maximum completion tokens for lyrics generation.", "maximum": 4000, "minimum": 500, "type": "number" }, "model": { "description": "Optional lyrics model override. Defaults to the configured lyrics model.", "maxLength": 120, "type": "string" }, "mood": { "maxLength": 200, "type": "string", "description": "Requested musical or visual mood." }, "multilingualMode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "sectioned", "type": "string" }, { "const": "blended", "type": "string" }, { "const": "call_and_response", "type": "string" } ], "description": "How multiple languages should be mixed." }, "negativeConstraints": { "items": { "maxLength": 80, "type": "string" }, "type": "array", "description": "Topics, styles, or tropes the output should avoid." }, "perspective": { "anyOf": [ { "const": "first_person", "type": "string" }, { "const": "second_person", "type": "string" }, { "const": "third_person", "type": "string" }, { "const": "mixed", "type": "string" } ], "description": "Requested lyric narrative perspective." }, "prompt": { "description": "Core song brief, story, scene, or hook idea.", "maxLength": 2000, "type": "string" }, "structure": { "items": { "maxLength": 50, "type": "string" }, "type": "array", "description": "Requested lyric section order." }, "temperature": { "description": "Sampling temperature for lyrics generation.", "maximum": 2, "minimum": 0, "type": "number" }, "themeKeywords": { "items": { "maxLength": 60, "type": "string" }, "type": "array", "description": "Short theme anchors for structured lyrics." }, "vocalStyle": { "maxLength": 200, "type": "string", "description": "Requested vocal performance direction." } }, "required": [ "prompt" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "gpt/gpt-4.1-mini/lyrics-generation", "gpt/gpt-4.1/lyrics-generation", "gpt/gpt-4o-mini/lyrics-generation", "gpt/gpt-4o/lyrics-generation" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "anyOf": [ { "additionalProperties": false, "properties": { "aspectRatio": { "anyOf": [ { "const": "16:9", "type": "string" }, { "const": "9:16", "type": "string" }, { "const": "1:1", "type": "string" }, { "const": "4:3", "type": "string" }, { "const": "3:4", "type": "string" } ], "description": "Requested output aspect ratio." }, "characterImage": { "minLength": 1, "type": "string", "description": "Public character reference image URL." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "generation": { "additionalProperties": false, "properties": { "creativeMode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "lyrics_story", "type": "string" }, { "const": "prompt_story", "type": "string" }, { "const": "mood_visual", "type": "string" }, { "const": "performance", "type": "string" } ], "description": "Creative intent used by Fast MV prompt and reference planning." }, "lipReferenceImages": { "description": "Ordered Premium V2 singer portrait URLs; the first item maps to the first singer.", "items": { "minLength": 1, "type": "string" }, "maxItems": 2, "minItems": 1, "type": "array" }, "managedVersion": { "anyOf": [ { "const": "oneclick-v1", "type": "string" }, { "const": "premium-v2", "type": "string" } ], "description": "Managed Fast MV engine version. Existing clients default to oneclick-v1; premium-v2 must be selected explicitly." }, "motionPreset": { "anyOf": [ { "const": "stable_performance", "type": "string" }, { "const": "cinematic_light", "type": "string" }, { "const": "dynamic_dance", "type": "string" }, { "const": "lip_sync_closeup", "type": "string" } ], "description": "Fast MV motion prompt policy." }, "performanceMode": { "anyOf": [ { "const": "sing", "type": "string" }, { "const": "sing_perform", "type": "string" }, { "const": "perform", "type": "string" }, { "const": "dance", "type": "string" } ], "description": "Premium V2 performance mode: singing, singing with performance, instrumental performance, or dance." }, "promptMode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "verbatim", "type": "string" }, { "const": "creative_brief", "type": "string" } ], "description": "Whether Fast MV preserves or compiles the caller prompt." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "high", "type": "string" } ], "description": "Requested public quality tier." }, "referenceStrategy": { "anyOf": [ { "const": "direct", "type": "string" }, { "const": "synthesize", "type": "string" } ], "description": "Fast MV policy for direct or synthesized references." }, "style": { "maxLength": 200, "type": "string", "description": "Requested creative style direction." }, "subtitleMode": { "anyOf": [ { "const": "vidu", "type": "string" }, { "const": "custom", "type": "string" } ], "description": "Fast MV subtitle rendering mode." }, "visualBoard": { "additionalProperties": false, "properties": { "imageProvider": { "anyOf": [ { "const": "gpt-image-2", "type": "string" }, { "const": "p-image", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public image-generation option code." }, "preset": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "speed", "type": "string" }, { "const": "detail", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Visual Board speed/detail policy." } }, "type": "object", "description": "Fast MV Visual Board configuration." } }, "type": "object", "description": "Product-specific generation controls." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "lipSync": { "type": "boolean", "description": "Whether the MV should use the supported lip-sync workflow." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "fast", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "preflightId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Reusable MV preflight snapshot identifier." }, "prompt": { "maxLength": 3000, "type": "string", "description": "Primary creative or operation instruction." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "referenceImages": { "items": { "minLength": 1, "type": "string" }, "maxItems": 7, "type": "array", "description": "Public reference image URLs." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "source": { "anyOf": [ { "additionalProperties": false, "properties": { "clipId": { "minLength": 1, "type": "string", "description": "Source clip identifier." }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "suno", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "clipId" ], "type": "object" }, { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "description": "Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.", "exclusiveMinimum": 0, "type": "number" }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object" } ], "description": "Public source media or product reference." }, "srtUrl": { "minLength": 1, "type": "string", "description": "Public URL of caller-supplied SRT subtitles." }, "subtitle": { "additionalProperties": false, "properties": { "fallback": { "anyOf": [ { "const": "fail", "type": "string" }, { "const": "continue_without_subtitles", "type": "string" } ], "description": "Behavior when the preferred subtitle path cannot complete." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." }, "mode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "provided", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Operation or product mode discriminator for this schema variant." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "premium", "type": "string" } ], "description": "Requested public quality tier." }, "required": { "type": "boolean", "description": "Whether the selected subtitle policy must succeed." } }, "type": "object", "description": "MV subtitle generation and fallback policy." }, "subtitleColor": { "maxLength": 20, "type": "string", "description": "Requested subtitle foreground color." }, "subtitles": { "type": "boolean", "description": "Whether subtitles are enabled for the MV." }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "mode", "source" ], "type": "object" }, { "additionalProperties": false, "properties": { "aspectRatio": { "anyOf": [ { "const": "16:9", "type": "string" }, { "const": "9:16", "type": "string" }, { "const": "1:1", "type": "string" }, { "const": "4:3", "type": "string" }, { "const": "3:4", "type": "string" } ], "description": "Requested output aspect ratio." }, "characterImage": { "minLength": 1, "type": "string", "description": "Public character reference image URL." }, "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "generation": { "additionalProperties": false, "properties": { "imageProvider": { "anyOf": [ { "const": "p-image", "type": "string" }, { "const": "gpt-image-2", "type": "string" }, { "const": "viduq2", "type": "string" } ], "description": "Public image-generation option code." }, "videoModel": { "maxLength": 100, "type": "string", "description": "Public scene-video model code." }, "videoProvider": { "anyOf": [ { "const": "p-video", "type": "string" }, { "const": "hailuo", "type": "string" }, { "const": "vidu", "type": "string" } ], "description": "Public scene-video option code." } }, "type": "object", "description": "Product-specific generation controls." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "lipSync": { "type": "boolean", "description": "Whether the MV should use the supported lip-sync workflow." }, "maxCredits": { "minimum": 1, "type": "number", "description": "Maximum OmnAPI credits authorized for this paid request." }, "mode": { "const": "studio", "type": "string", "description": "Operation or product mode discriminator for this schema variant." }, "preflightId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Reusable MV preflight snapshot identifier." }, "prompt": { "maxLength": 3000, "type": "string", "description": "Primary creative or operation instruction." }, "quoteId": { "maxLength": 100, "minLength": 1, "type": "string", "description": "Short-lived quote identifier for the matching paid operation." }, "referenceImages": { "items": { "minLength": 1, "type": "string" }, "maxItems": 7, "type": "array", "description": "Public reference image URLs." }, "resolution": { "anyOf": [ { "const": "540p", "type": "string" }, { "const": "720p", "type": "string" }, { "const": "1080p", "type": "string" } ], "description": "Requested output resolution." }, "source": { "anyOf": [ { "additionalProperties": false, "properties": { "clipId": { "minLength": 1, "type": "string", "description": "Source clip identifier." }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "suno", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "clipId" ], "type": "object" }, { "additionalProperties": false, "properties": { "audioUrl": { "format": "uri", "type": "string", "description": "Public HTTP(S) audio URL." }, "durationSec": { "description": "Optional original-source duration hint. The server downloads and probes the public audio URL with server-side media validation, validates this hint, and transparently segments Fast output up to 600 seconds.", "exclusiveMinimum": 0, "type": "number" }, "lyrics": { "maxLength": 5000, "type": "string", "description": "Lyrics or lyric context supplied to the operation." }, "range": { "properties": { "endSec": { "minimum": 0, "type": "number", "description": "Scene or source-range end time in seconds." }, "startSec": { "minimum": 0, "type": "number", "description": "Scene or source-range start time in seconds." } }, "type": "object", "description": "Optional source-media range." }, "type": { "const": "audio", "type": "string", "description": "Source or product type discriminator." } }, "required": [ "type", "audioUrl" ], "type": "object" } ], "description": "Public source media or product reference." }, "srtUrl": { "minLength": 1, "type": "string", "description": "Public URL of caller-supplied SRT subtitles." }, "subtitle": { "additionalProperties": false, "properties": { "fallback": { "anyOf": [ { "const": "fail", "type": "string" }, { "const": "continue_without_subtitles", "type": "string" } ], "description": "Behavior when the preferred subtitle path cannot complete." }, "language": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "en", "type": "string" }, { "const": "zh", "type": "string" } ], "description": "Requested or known language code/name." }, "maxCostUsdPerMin": { "maximum": 1, "minimum": 0.001, "type": "number", "description": "Maximum accepted public subtitle price in USD per minute." }, "mode": { "anyOf": [ { "const": "auto", "type": "string" }, { "const": "provided", "type": "string" }, { "const": "off", "type": "string" } ], "description": "Operation or product mode discriminator for this schema variant." }, "quality": { "anyOf": [ { "const": "standard", "type": "string" }, { "const": "premium", "type": "string" } ], "description": "Requested public quality tier." }, "required": { "type": "boolean", "description": "Whether the selected subtitle policy must succeed." } }, "type": "object", "description": "MV subtitle generation and fallback policy." }, "subtitleColor": { "maxLength": 20, "type": "string", "description": "Requested subtitle foreground color." }, "subtitles": { "type": "boolean", "description": "Whether subtitles are enabled for the MV." }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "mode", "source" ], "type": "object" } ], "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "mv/mv-managed-basic/generate-managed-mv" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "height": { "default": 1024, "maximum": 2048, "minimum": 256, "type": "number", "description": "Requested image height in pixels for this model branch." }, "prompt": { "description": "Image generation prompt", "maxLength": 2000, "type": "string" }, "style": { "maxLength": 100, "type": "string", "description": "Requested creative style direction." }, "width": { "default": 1024, "maximum": 2048, "minimum": 256, "type": "number", "description": "Requested image width in pixels for this model branch." } }, "required": [ "prompt" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "producer/lyria-3-5/generate-image", "producer/lyria-3-preview/generate-image", "producer/lyria-3-pro/generate-image" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "numVerses": { "maximum": 10, "minimum": 1, "type": "number", "description": "Requested number of lyric verses." }, "prompt": { "description": "Text prompt for lyrics generation", "maxLength": 3000, "type": "string" }, "style": { "maxLength": 200, "type": "string", "description": "Requested creative style direction." } }, "required": [ "prompt" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "producer/lyria-3-5/generate-lyrics", "producer/lyria-3-preview/generate-lyrics", "producer/lyria-3-pro/generate-lyrics" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "advancedMode": { "default": false, "deprecated": true, "description": "Deprecated compatibility field; Producer compose ignores this value.", "type": "boolean" }, "bpm": { "description": "Optional BPM hint", "maximum": 999, "minimum": 1, "type": "number" }, "conversationId": { "type": "string", "description": "Existing Producer conversation identifier to continue." }, "currentSongId": { "description": "Optional current song id used for queue/context continuity", "type": "string" }, "imageId": { "description": "Optional cover image id", "type": "string" }, "imagePrompt": { "description": "Optional prompt for generating a cover image", "maxLength": 1000, "type": "string" }, "instrumental": { "default": false, "description": "Whether to force instrumental generation", "type": "boolean" }, "length": { "description": "Optional length hint in seconds. Lyria 3.5 requires 60-180 seconds; Lyria 3 Pro accepts shorter values.", "maximum": 180, "minimum": 1, "type": "number" }, "lyrics": { "description": "Optional lyrics text for compose generation. If omitted while instrumental=false, OmnAPI auto-generates lyrics before compose.", "maxLength": 3000, "type": "string" }, "lyricsId": { "description": "Optional existing lyrics id", "type": "string" }, "model": { "anyOf": [ { "const": "Lyria 3.5", "type": "string" }, { "const": "Lyria 3 Pro", "type": "string" }, { "const": "Lyria 3 preview", "deprecated": true, "type": "string" } ], "description": "Producer music model. 'Lyria 3 preview' is accepted as a deprecated alias for Lyria 3.5." }, "seed": { "description": "Optional seed value", "minimum": 0, "type": "number" }, "soundPrompt": { "description": "Sound prompt for music generation", "maxLength": 500, "type": "string" }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." } }, "required": [ "soundPrompt" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "producer/lyria-3-5/generate-music-compose", "producer/lyria-3-preview/generate-music-compose", "producer/lyria-3-pro/generate-music-compose" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "clipId": { "description": "Source clip id to modify", "type": "string" }, "conversationId": { "description": "Optional existing conversation id to reuse", "type": "string" }, "cropEndAt": { "deprecated": true, "description": "Deprecated alias for extendFromSeconds", "minimum": 0, "type": "number" }, "currentSongId": { "description": "Optional current song id for client_context; defaults to clipId", "type": "string" }, "extendFromSeconds": { "description": "Source timestamp where extension begins", "minimum": 0, "type": "number" }, "extendSeconds": { "default": 60, "description": "Seconds generated by ExtendSection", "exclusiveMinimum": 0, "maximum": 180, "type": "number" }, "imageId": { "description": "Optional output cover image id", "type": "string" }, "lyrics": { "description": "New lyrics (useful for cover / swap_vocals)", "maxLength": 3000, "type": "string" }, "lyricsId": { "description": "Optional lyrics id paired with lyrics when using conversation-based modify flows", "type": "string" }, "modifyMode": { "anyOf": [ { "const": "task", "type": "string" }, { "const": "conversation", "type": "string" } ], "description": "Modify transport: 'task' uses Recipe + audio__render_edit; 'conversation' lets Producer interpret a legacy/agentic request first." }, "prompt": { "description": "Additional modification instructions", "maxLength": 1000, "type": "string" }, "regions": { "description": "Ordered, non-overlapping regions for ReplaceSection", "items": { "additionalProperties": false, "properties": { "end": { "description": "Region end timestamp in seconds", "exclusiveMinimum": 0, "type": "number" }, "start": { "description": "Region start timestamp in seconds", "minimum": 0, "type": "number" } }, "required": [ "start", "end" ], "type": "object" }, "minItems": 1, "type": "array" }, "replaceEndAt": { "deprecated": true, "description": "Deprecated single-region alias for regions[].end", "minimum": 0, "type": "number" }, "replaceStartAt": { "deprecated": true, "description": "Deprecated single-region alias for regions[].start", "minimum": 0, "type": "number" }, "seed": { "description": "Optional deterministic seed for the modification", "minimum": 0, "type": "number" }, "soundPrompt": { "description": "New sound prompt (useful for swap_sound)", "maxLength": 500, "type": "string" }, "strength": { "default": 0.5, "description": "Cover similarity strength (0-1)", "maximum": 1, "minimum": 0, "type": "number" }, "tags": { "description": "Style tags for the modified clip", "maxLength": 300, "type": "string" }, "title": { "maxLength": 200, "type": "string", "description": "Optional customer-facing title." }, "transform": { "anyOf": [ { "const": "extend", "type": "string" }, { "const": "cover", "type": "string" }, { "const": "replace", "type": "string" }, { "const": "inpaint", "deprecated": true, "type": "string" }, { "const": "swap_vocals", "deprecated": true, "type": "string" }, { "const": "swap_sound", "deprecated": true, "type": "string" } ], "description": "Current deterministic edit type. inpaint is a deprecated alias for replace; swap_* use the legacy conversation path." } }, "required": [ "clipId", "transform" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "producer/lyria-3-5/generate-music-modify", "producer/lyria-3-preview/generate-music-modify", "producer/lyria-3-pro/generate-music-modify" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "clipId": { "description": "Clip ID to analyze", "type": "string" } }, "required": [ "clipId" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "suno/chirp-auk-turbo/get-audio-analysis", "suno/chirp-auk/get-audio-analysis", "suno/chirp-bluejay/get-audio-analysis", "suno/chirp-crow/get-audio-analysis", "suno/chirp-fenix/get-audio-analysis", "suno/chirp-goose/get-audio-analysis", "suno/chirp-hawk-wild/get-audio-analysis", "suno/chirp-hawk/get-audio-analysis", "suno/chirp-v4/get-audio-analysis", "suno/chirp_auk/get-audio-analysis", "suno/chirp_auk_turbo/get-audio-analysis", "suno/chirp_bluejay/get-audio-analysis", "suno/chirp_crow/get-audio-analysis", "suno/chirp_fenix/get-audio-analysis", "suno/chirp_v4/get-audio-analysis" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "clipId": { "description": "Clip ID to fetch detail for", "type": "string" } }, "required": [ "clipId" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "suno/chirp-auk-turbo/get-clip-detail", "suno/chirp-auk/get-clip-detail", "suno/chirp-bluejay/get-clip-detail", "suno/chirp-crow/get-clip-detail", "suno/chirp-fenix/get-clip-detail", "suno/chirp-goose/get-clip-detail", "suno/chirp-hawk-wild/get-clip-detail", "suno/chirp-hawk/get-clip-detail", "suno/chirp-v4/get-clip-detail", "suno/chirp_auk/get-clip-detail", "suno/chirp_auk_turbo/get-clip-detail", "suno/chirp_bluejay/get-clip-detail", "suno/chirp_crow/get-clip-detail", "suno/chirp_fenix/get-clip-detail", "suno/chirp_v4/get-clip-detail" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "clipId": { "description": "Clip ID to get lyrics timeline for", "type": "string" } }, "required": [ "clipId" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "suno/chirp-auk-turbo/get-lyrics-timeline", "suno/chirp-auk/get-lyrics-timeline", "suno/chirp-bluejay/get-lyrics-timeline", "suno/chirp-crow/get-lyrics-timeline", "suno/chirp-fenix/get-lyrics-timeline", "suno/chirp-goose/get-lyrics-timeline", "suno/chirp-hawk-wild/get-lyrics-timeline", "suno/chirp-hawk/get-lyrics-timeline", "suno/chirp-v4/get-lyrics-timeline", "suno/chirp_auk/get-lyrics-timeline", "suno/chirp_auk_turbo/get-lyrics-timeline", "suno/chirp_bluejay/get-lyrics-timeline", "suno/chirp_crow/get-lyrics-timeline", "suno/chirp_fenix/get-lyrics-timeline", "suno/chirp_v4/get-lyrics-timeline" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "voiceId": { "description": "Voice ID to fetch", "type": "string" } }, "required": [ "voiceId" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "suno/chirp-auk-turbo/get-persona", "suno/chirp-auk-turbo/get-voice", "suno/chirp-auk/get-persona", "suno/chirp-auk/get-voice", "suno/chirp-bluejay/get-persona", "suno/chirp-bluejay/get-voice", "suno/chirp-crow/get-persona", "suno/chirp-crow/get-voice", "suno/chirp-fenix/get-persona", "suno/chirp-fenix/get-voice", "suno/chirp-goose/get-persona", "suno/chirp-goose/get-voice", "suno/chirp-hawk-wild/get-persona", "suno/chirp-hawk-wild/get-voice", "suno/chirp-hawk/get-persona", "suno/chirp-hawk/get-voice", "suno/chirp-v4/get-persona", "suno/chirp-v4/get-voice", "suno/chirp_auk/get-persona", "suno/chirp_auk/get-voice", "suno/chirp_auk_turbo/get-persona", "suno/chirp_auk_turbo/get-voice", "suno/chirp_bluejay/get-persona", "suno/chirp_bluejay/get-voice", "suno/chirp_crow/get-persona", "suno/chirp_crow/get-voice", "suno/chirp_fenix/get-persona", "suno/chirp_fenix/get-voice", "suno/chirp_v4/get-persona", "suno/chirp_v4/get-voice" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "page": { "default": 1, "minimum": 1, "type": "number", "description": "One-based result page." } }, "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "suno/chirp-auk-turbo/list-personas", "suno/chirp-auk-turbo/list-voices", "suno/chirp-auk/list-personas", "suno/chirp-auk/list-voices", "suno/chirp-bluejay/list-personas", "suno/chirp-bluejay/list-voices", "suno/chirp-crow/list-personas", "suno/chirp-crow/list-voices", "suno/chirp-fenix/list-personas", "suno/chirp-fenix/list-voices", "suno/chirp-goose/list-personas", "suno/chirp-goose/list-voices", "suno/chirp-hawk-wild/list-personas", "suno/chirp-hawk-wild/list-voices", "suno/chirp-hawk/list-personas", "suno/chirp-hawk/list-voices", "suno/chirp-v4/list-personas", "suno/chirp-v4/list-voices", "suno/chirp_auk/list-personas", "suno/chirp_auk/list-voices", "suno/chirp_auk_turbo/list-personas", "suno/chirp_auk_turbo/list-voices", "suno/chirp_bluejay/list-personas", "suno/chirp_bluejay/list-voices", "suno/chirp_crow/list-personas", "suno/chirp_crow/list-voices", "suno/chirp_fenix/list-personas", "suno/chirp_fenix/list-voices", "suno/chirp_v4/list-personas", "suno/chirp_v4/list-voices" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "additionalProperties": true, "properties": { "createSessionToken": { "description": "Optional create session token", "type": "string" }, "lyricsModel": { "const": "default", "description": "Only the stable \"default\" lyrics model is supported for paired candidates", "type": "string" }, "prompt": { "description": "Text prompt for generating two lyrics candidates", "maxLength": 3000, "type": "string" }, "source": { "description": "Caller source tag retained in Task audit input", "maxLength": 100, "type": "string" } }, "required": [ "prompt" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "suno/chirp-auk-turbo/lyrics-pair", "suno/chirp-auk/lyrics-pair", "suno/chirp-bluejay/lyrics-pair", "suno/chirp-crow/lyrics-pair", "suno/chirp-fenix/lyrics-pair", "suno/chirp-goose/lyrics-pair", "suno/chirp-hawk-wild/lyrics-pair", "suno/chirp-hawk/lyrics-pair", "suno/chirp-v4/lyrics-pair", "suno/chirp_auk/lyrics-pair", "suno/chirp_auk_turbo/lyrics-pair", "suno/chirp_bluejay/lyrics-pair", "suno/chirp_crow/lyrics-pair", "suno/chirp_fenix/lyrics-pair", "suno/chirp_v4/lyrics-pair" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "mids": { "anyOf": [ { "description": "Comma-separated clip IDs", "type": "string" }, { "description": "Array of clip IDs", "items": { "type": "string" }, "type": "array" } ], "description": "Clip identifiers accepted by this model branch." }, "version": { "anyOf": [ { "const": "v2", "type": "string" }, { "const": "v3", "type": "string" } ], "description": "Requested compatibility or resource version." } }, "required": [ "mids" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "suno/chirp-auk-turbo/query-songs", "suno/chirp-auk/query-songs", "suno/chirp-bluejay/query-songs", "suno/chirp-crow/query-songs", "suno/chirp-fenix/query-songs", "suno/chirp-goose/query-songs", "suno/chirp-hawk-wild/query-songs", "suno/chirp-hawk/query-songs", "suno/chirp-v4/query-songs", "suno/chirp_auk/query-songs", "suno/chirp_auk_turbo/query-songs", "suno/chirp_bluejay/query-songs", "suno/chirp_crow/query-songs", "suno/chirp_fenix/query-songs", "suno/chirp_v4/query-songs" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "excludedStyles": { "items": { "description": "Styles to exclude from recommendations", "type": "string" }, "type": "array", "description": "Styles to exclude from the generated result." } }, "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "suno/chirp-auk-turbo/recommend-styles", "suno/chirp-auk/recommend-styles", "suno/chirp-bluejay/recommend-styles", "suno/chirp-crow/recommend-styles", "suno/chirp-fenix/recommend-styles", "suno/chirp-goose/recommend-styles", "suno/chirp-hawk-wild/recommend-styles", "suno/chirp-hawk/recommend-styles", "suno/chirp-v4/recommend-styles", "suno/chirp_auk/recommend-styles", "suno/chirp_auk_turbo/recommend-styles", "suno/chirp_bluejay/recommend-styles", "suno/chirp_crow/recommend-styles", "suno/chirp_fenix/recommend-styles", "suno/chirp_v4/recommend-styles" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "properties": { "prompt": { "description": "Text prompt for lyrics generation", "maxLength": 3000, "type": "string" } }, "required": [ "prompt" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "suno/chirp-auk-turbo/text-to-lyrics", "suno/chirp-auk/text-to-lyrics", "suno/chirp-bluejay/text-to-lyrics", "suno/chirp-crow/text-to-lyrics", "suno/chirp-fenix/text-to-lyrics", "suno/chirp-goose/text-to-lyrics", "suno/chirp-hawk-wild/text-to-lyrics", "suno/chirp-hawk/text-to-lyrics", "suno/chirp-v4/text-to-lyrics", "suno/chirp_auk/text-to-lyrics", "suno/chirp_auk_turbo/text-to-lyrics", "suno/chirp_bluejay/text-to-lyrics", "suno/chirp_crow/text-to-lyrics", "suno/chirp_fenix/text-to-lyrics", "suno/chirp_v4/text-to-lyrics" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" }, { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "additionalProperties": true, "properties": { "isInstrumental": { "default": false, "type": "boolean", "description": "Optional instrumental intent for the derived result." }, "prompt": { "description": "Text prompt for simple music generation (GPT description)", "maxLength": 2000, "type": "string" }, "waitAudio": { "default": true, "type": "boolean", "description": "Whether this model branch waits for playable audio before completion." } }, "required": [ "prompt" ], "type": "object", "description": "Feature-specific input matching the selected model path." }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "description": "Public model path in format \"providerCode/modelCode/featureCode\".", "enum": [ "suno/chirp-auk-turbo/text-to-music-simple", "suno/chirp-auk/text-to-music-simple", "suno/chirp-bluejay/text-to-music-simple", "suno/chirp-crow/text-to-music-simple", "suno/chirp-fenix/text-to-music-simple", "suno/chirp-goose/text-to-music-simple", "suno/chirp-hawk-wild/text-to-music-simple", "suno/chirp-hawk/text-to-music-simple", "suno/chirp-v4/text-to-music-simple", "suno/chirp_auk/text-to-music-simple", "suno/chirp_auk_turbo/text-to-music-simple", "suno/chirp_bluejay/text-to-music-simple", "suno/chirp_crow/text-to-music-simple", "suno/chirp_fenix/text-to-music-simple", "suno/chirp_v4/text-to-music-simple" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" } ], "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "description": "Input parameters for the task", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "default": "gpt/gpt-4.1-mini/lyrics-generation", "description": "Public model path in format \"providerCode/modelCode/featureCode\". Legacy Suno model names remain accepted and execute on their V6 equivalents while retaining the requested pricing identity.", "enum": [ "gpt/gpt-4.1-mini/lyrics-generation", "gpt/gpt-4.1/lyrics-generation", "gpt/gpt-4o-mini/lyrics-generation", "gpt/gpt-4o/lyrics-generation", "mv/mv-managed-basic/generate-managed-mv", "producer/lyria-3-5/generate-image", "producer/lyria-3-5/generate-lyrics", "producer/lyria-3-5/generate-music-compose", "producer/lyria-3-5/generate-music-modify", "producer/lyria-3-preview/generate-image", "producer/lyria-3-preview/generate-lyrics", "producer/lyria-3-preview/generate-music-compose", "producer/lyria-3-preview/generate-music-modify", "producer/lyria-3-pro/generate-image", "producer/lyria-3-pro/generate-lyrics", "producer/lyria-3-pro/generate-music-compose", "producer/lyria-3-pro/generate-music-modify", "suno/chirp-auk-turbo/get-audio-analysis", "suno/chirp-auk-turbo/get-clip-detail", "suno/chirp-auk-turbo/get-lyrics-timeline", "suno/chirp-auk-turbo/get-persona", "suno/chirp-auk-turbo/get-voice", "suno/chirp-auk-turbo/list-personas", "suno/chirp-auk-turbo/list-voices", "suno/chirp-auk-turbo/lyrics-pair", "suno/chirp-auk-turbo/query-songs", "suno/chirp-auk-turbo/recommend-styles", "suno/chirp-auk-turbo/text-to-lyrics", "suno/chirp-auk-turbo/text-to-music-simple", "suno/chirp-auk/get-audio-analysis", "suno/chirp-auk/get-clip-detail", "suno/chirp-auk/get-lyrics-timeline", "suno/chirp-auk/get-persona", "suno/chirp-auk/get-voice", "suno/chirp-auk/list-personas", "suno/chirp-auk/list-voices", "suno/chirp-auk/lyrics-pair", "suno/chirp-auk/query-songs", "suno/chirp-auk/recommend-styles", "suno/chirp-auk/text-to-lyrics", "suno/chirp-auk/text-to-music-simple", "suno/chirp-bluejay/get-audio-analysis", "suno/chirp-bluejay/get-clip-detail", "suno/chirp-bluejay/get-lyrics-timeline", "suno/chirp-bluejay/get-persona", "suno/chirp-bluejay/get-voice", "suno/chirp-bluejay/list-personas", "suno/chirp-bluejay/list-voices", "suno/chirp-bluejay/lyrics-pair", "suno/chirp-bluejay/query-songs", "suno/chirp-bluejay/recommend-styles", "suno/chirp-bluejay/text-to-lyrics", "suno/chirp-bluejay/text-to-music-simple", "suno/chirp-crow/get-audio-analysis", "suno/chirp-crow/get-clip-detail", "suno/chirp-crow/get-lyrics-timeline", "suno/chirp-crow/get-persona", "suno/chirp-crow/get-voice", "suno/chirp-crow/list-personas", "suno/chirp-crow/list-voices", "suno/chirp-crow/lyrics-pair", "suno/chirp-crow/query-songs", "suno/chirp-crow/recommend-styles", "suno/chirp-crow/text-to-lyrics", "suno/chirp-crow/text-to-music-simple", "suno/chirp-fenix/get-audio-analysis", "suno/chirp-fenix/get-clip-detail", "suno/chirp-fenix/get-lyrics-timeline", "suno/chirp-fenix/get-persona", "suno/chirp-fenix/get-voice", "suno/chirp-fenix/list-personas", "suno/chirp-fenix/list-voices", "suno/chirp-fenix/lyrics-pair", "suno/chirp-fenix/query-songs", "suno/chirp-fenix/recommend-styles", "suno/chirp-fenix/text-to-lyrics", "suno/chirp-fenix/text-to-music-simple", "suno/chirp-goose/get-audio-analysis", "suno/chirp-goose/get-clip-detail", "suno/chirp-goose/get-lyrics-timeline", "suno/chirp-goose/get-persona", "suno/chirp-goose/get-voice", "suno/chirp-goose/list-personas", "suno/chirp-goose/list-voices", "suno/chirp-goose/lyrics-pair", "suno/chirp-goose/query-songs", "suno/chirp-goose/recommend-styles", "suno/chirp-goose/text-to-lyrics", "suno/chirp-goose/text-to-music-simple", "suno/chirp-hawk-wild/get-audio-analysis", "suno/chirp-hawk-wild/get-clip-detail", "suno/chirp-hawk-wild/get-lyrics-timeline", "suno/chirp-hawk-wild/get-persona", "suno/chirp-hawk-wild/get-voice", "suno/chirp-hawk-wild/list-personas", "suno/chirp-hawk-wild/list-voices", "suno/chirp-hawk-wild/lyrics-pair", "suno/chirp-hawk-wild/query-songs", "suno/chirp-hawk-wild/recommend-styles", "suno/chirp-hawk-wild/text-to-lyrics", "suno/chirp-hawk-wild/text-to-music-simple", "suno/chirp-hawk/get-audio-analysis", "suno/chirp-hawk/get-clip-detail", "suno/chirp-hawk/get-lyrics-timeline", "suno/chirp-hawk/get-persona", "suno/chirp-hawk/get-voice", "suno/chirp-hawk/list-personas", "suno/chirp-hawk/list-voices", "suno/chirp-hawk/lyrics-pair", "suno/chirp-hawk/query-songs", "suno/chirp-hawk/recommend-styles", "suno/chirp-hawk/text-to-lyrics", "suno/chirp-hawk/text-to-music-simple", "suno/chirp-v4/get-audio-analysis", "suno/chirp-v4/get-clip-detail", "suno/chirp-v4/get-lyrics-timeline", "suno/chirp-v4/get-persona", "suno/chirp-v4/get-voice", "suno/chirp-v4/list-personas", "suno/chirp-v4/list-voices", "suno/chirp-v4/lyrics-pair", "suno/chirp-v4/query-songs", "suno/chirp-v4/recommend-styles", "suno/chirp-v4/text-to-lyrics", "suno/chirp-v4/text-to-music-simple", "suno/chirp_auk/get-audio-analysis", "suno/chirp_auk/get-clip-detail", "suno/chirp_auk/get-lyrics-timeline", "suno/chirp_auk/get-persona", "suno/chirp_auk/get-voice", "suno/chirp_auk/list-personas", "suno/chirp_auk/list-voices", "suno/chirp_auk/lyrics-pair", "suno/chirp_auk/query-songs", "suno/chirp_auk/recommend-styles", "suno/chirp_auk/text-to-lyrics", "suno/chirp_auk/text-to-music-simple", "suno/chirp_auk_turbo/get-audio-analysis", "suno/chirp_auk_turbo/get-clip-detail", "suno/chirp_auk_turbo/get-lyrics-timeline", "suno/chirp_auk_turbo/get-persona", "suno/chirp_auk_turbo/get-voice", "suno/chirp_auk_turbo/list-personas", "suno/chirp_auk_turbo/list-voices", "suno/chirp_auk_turbo/lyrics-pair", "suno/chirp_auk_turbo/query-songs", "suno/chirp_auk_turbo/recommend-styles", "suno/chirp_auk_turbo/text-to-lyrics", "suno/chirp_auk_turbo/text-to-music-simple", "suno/chirp_bluejay/get-audio-analysis", "suno/chirp_bluejay/get-clip-detail", "suno/chirp_bluejay/get-lyrics-timeline", "suno/chirp_bluejay/get-persona", "suno/chirp_bluejay/get-voice", "suno/chirp_bluejay/list-personas", "suno/chirp_bluejay/list-voices", "suno/chirp_bluejay/lyrics-pair", "suno/chirp_bluejay/query-songs", "suno/chirp_bluejay/recommend-styles", "suno/chirp_bluejay/text-to-lyrics", "suno/chirp_bluejay/text-to-music-simple", "suno/chirp_crow/get-audio-analysis", "suno/chirp_crow/get-clip-detail", "suno/chirp_crow/get-lyrics-timeline", "suno/chirp_crow/get-persona", "suno/chirp_crow/get-voice", "suno/chirp_crow/list-personas", "suno/chirp_crow/list-voices", "suno/chirp_crow/lyrics-pair", "suno/chirp_crow/query-songs", "suno/chirp_crow/recommend-styles", "suno/chirp_crow/text-to-lyrics", "suno/chirp_crow/text-to-music-simple", "suno/chirp_fenix/get-audio-analysis", "suno/chirp_fenix/get-clip-detail", "suno/chirp_fenix/get-lyrics-timeline", "suno/chirp_fenix/get-persona", "suno/chirp_fenix/get-voice", "suno/chirp_fenix/list-personas", "suno/chirp_fenix/list-voices", "suno/chirp_fenix/lyrics-pair", "suno/chirp_fenix/query-songs", "suno/chirp_fenix/recommend-styles", "suno/chirp_fenix/text-to-lyrics", "suno/chirp_fenix/text-to-music-simple", "suno/chirp_v4/get-audio-analysis", "suno/chirp_v4/get-clip-detail", "suno/chirp_v4/get-lyrics-timeline", "suno/chirp_v4/get-persona", "suno/chirp_v4/get-voice", "suno/chirp_v4/list-personas", "suno/chirp_v4/list-voices", "suno/chirp_v4/lyrics-pair", "suno/chirp_v4/query-songs", "suno/chirp_v4/recommend-styles", "suno/chirp_v4/text-to-lyrics", "suno/chirp_v4/text-to-music-simple" ], "examples": [ "gpt/gpt-4.1-mini/lyrics-generation", "gpt/gpt-4.1/lyrics-generation", "gpt/gpt-4o-mini/lyrics-generation", "gpt/gpt-4o/lyrics-generation", "mv/mv-managed-basic/generate-managed-mv" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "description": "Input parameters for the task", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "default": "gpt/gpt-4.1-mini/lyrics-generation", "description": "Public model path in format \"providerCode/modelCode/featureCode\". Legacy Suno model names remain accepted and execute on their V6 equivalents while retaining the requested pricing identity.", "enum": [ "gpt/gpt-4.1-mini/lyrics-generation", "gpt/gpt-4.1/lyrics-generation", "gpt/gpt-4o-mini/lyrics-generation", "gpt/gpt-4o/lyrics-generation", "mv/mv-managed-basic/generate-managed-mv", "producer/lyria-3-5/generate-image", "producer/lyria-3-5/generate-lyrics", "producer/lyria-3-5/generate-music-compose", "producer/lyria-3-5/generate-music-modify", "producer/lyria-3-preview/generate-image", "producer/lyria-3-preview/generate-lyrics", "producer/lyria-3-preview/generate-music-compose", "producer/lyria-3-preview/generate-music-modify", "producer/lyria-3-pro/generate-image", "producer/lyria-3-pro/generate-lyrics", "producer/lyria-3-pro/generate-music-compose", "producer/lyria-3-pro/generate-music-modify", "suno/chirp-auk-turbo/get-audio-analysis", "suno/chirp-auk-turbo/get-clip-detail", "suno/chirp-auk-turbo/get-lyrics-timeline", "suno/chirp-auk-turbo/get-persona", "suno/chirp-auk-turbo/get-voice", "suno/chirp-auk-turbo/list-personas", "suno/chirp-auk-turbo/list-voices", "suno/chirp-auk-turbo/lyrics-pair", "suno/chirp-auk-turbo/query-songs", "suno/chirp-auk-turbo/recommend-styles", "suno/chirp-auk-turbo/text-to-lyrics", "suno/chirp-auk-turbo/text-to-music-simple", "suno/chirp-auk/get-audio-analysis", "suno/chirp-auk/get-clip-detail", "suno/chirp-auk/get-lyrics-timeline", "suno/chirp-auk/get-persona", "suno/chirp-auk/get-voice", "suno/chirp-auk/list-personas", "suno/chirp-auk/list-voices", "suno/chirp-auk/lyrics-pair", "suno/chirp-auk/query-songs", "suno/chirp-auk/recommend-styles", "suno/chirp-auk/text-to-lyrics", "suno/chirp-auk/text-to-music-simple", "suno/chirp-bluejay/get-audio-analysis", "suno/chirp-bluejay/get-clip-detail", "suno/chirp-bluejay/get-lyrics-timeline", "suno/chirp-bluejay/get-persona", "suno/chirp-bluejay/get-voice", "suno/chirp-bluejay/list-personas", "suno/chirp-bluejay/list-voices", "suno/chirp-bluejay/lyrics-pair", "suno/chirp-bluejay/query-songs", "suno/chirp-bluejay/recommend-styles", "suno/chirp-bluejay/text-to-lyrics", "suno/chirp-bluejay/text-to-music-simple", "suno/chirp-crow/get-audio-analysis", "suno/chirp-crow/get-clip-detail", "suno/chirp-crow/get-lyrics-timeline", "suno/chirp-crow/get-persona", "suno/chirp-crow/get-voice", "suno/chirp-crow/list-personas", "suno/chirp-crow/list-voices", "suno/chirp-crow/lyrics-pair", "suno/chirp-crow/query-songs", "suno/chirp-crow/recommend-styles", "suno/chirp-crow/text-to-lyrics", "suno/chirp-crow/text-to-music-simple", "suno/chirp-fenix/get-audio-analysis", "suno/chirp-fenix/get-clip-detail", "suno/chirp-fenix/get-lyrics-timeline", "suno/chirp-fenix/get-persona", "suno/chirp-fenix/get-voice", "suno/chirp-fenix/list-personas", "suno/chirp-fenix/list-voices", "suno/chirp-fenix/lyrics-pair", "suno/chirp-fenix/query-songs", "suno/chirp-fenix/recommend-styles", "suno/chirp-fenix/text-to-lyrics", "suno/chirp-fenix/text-to-music-simple", "suno/chirp-goose/get-audio-analysis", "suno/chirp-goose/get-clip-detail", "suno/chirp-goose/get-lyrics-timeline", "suno/chirp-goose/get-persona", "suno/chirp-goose/get-voice", "suno/chirp-goose/list-personas", "suno/chirp-goose/list-voices", "suno/chirp-goose/lyrics-pair", "suno/chirp-goose/query-songs", "suno/chirp-goose/recommend-styles", "suno/chirp-goose/text-to-lyrics", "suno/chirp-goose/text-to-music-simple", "suno/chirp-hawk-wild/get-audio-analysis", "suno/chirp-hawk-wild/get-clip-detail", "suno/chirp-hawk-wild/get-lyrics-timeline", "suno/chirp-hawk-wild/get-persona", "suno/chirp-hawk-wild/get-voice", "suno/chirp-hawk-wild/list-personas", "suno/chirp-hawk-wild/list-voices", "suno/chirp-hawk-wild/lyrics-pair", "suno/chirp-hawk-wild/query-songs", "suno/chirp-hawk-wild/recommend-styles", "suno/chirp-hawk-wild/text-to-lyrics", "suno/chirp-hawk-wild/text-to-music-simple", "suno/chirp-hawk/get-audio-analysis", "suno/chirp-hawk/get-clip-detail", "suno/chirp-hawk/get-lyrics-timeline", "suno/chirp-hawk/get-persona", "suno/chirp-hawk/get-voice", "suno/chirp-hawk/list-personas", "suno/chirp-hawk/list-voices", "suno/chirp-hawk/lyrics-pair", "suno/chirp-hawk/query-songs", "suno/chirp-hawk/recommend-styles", "suno/chirp-hawk/text-to-lyrics", "suno/chirp-hawk/text-to-music-simple", "suno/chirp-v4/get-audio-analysis", "suno/chirp-v4/get-clip-detail", "suno/chirp-v4/get-lyrics-timeline", "suno/chirp-v4/get-persona", "suno/chirp-v4/get-voice", "suno/chirp-v4/list-personas", "suno/chirp-v4/list-voices", "suno/chirp-v4/lyrics-pair", "suno/chirp-v4/query-songs", "suno/chirp-v4/recommend-styles", "suno/chirp-v4/text-to-lyrics", "suno/chirp-v4/text-to-music-simple", "suno/chirp_auk/get-audio-analysis", "suno/chirp_auk/get-clip-detail", "suno/chirp_auk/get-lyrics-timeline", "suno/chirp_auk/get-persona", "suno/chirp_auk/get-voice", "suno/chirp_auk/list-personas", "suno/chirp_auk/list-voices", "suno/chirp_auk/lyrics-pair", "suno/chirp_auk/query-songs", "suno/chirp_auk/recommend-styles", "suno/chirp_auk/text-to-lyrics", "suno/chirp_auk/text-to-music-simple", "suno/chirp_auk_turbo/get-audio-analysis", "suno/chirp_auk_turbo/get-clip-detail", "suno/chirp_auk_turbo/get-lyrics-timeline", "suno/chirp_auk_turbo/get-persona", "suno/chirp_auk_turbo/get-voice", "suno/chirp_auk_turbo/list-personas", "suno/chirp_auk_turbo/list-voices", "suno/chirp_auk_turbo/lyrics-pair", "suno/chirp_auk_turbo/query-songs", "suno/chirp_auk_turbo/recommend-styles", "suno/chirp_auk_turbo/text-to-lyrics", "suno/chirp_auk_turbo/text-to-music-simple", "suno/chirp_bluejay/get-audio-analysis", "suno/chirp_bluejay/get-clip-detail", "suno/chirp_bluejay/get-lyrics-timeline", "suno/chirp_bluejay/get-persona", "suno/chirp_bluejay/get-voice", "suno/chirp_bluejay/list-personas", "suno/chirp_bluejay/list-voices", "suno/chirp_bluejay/lyrics-pair", "suno/chirp_bluejay/query-songs", "suno/chirp_bluejay/recommend-styles", "suno/chirp_bluejay/text-to-lyrics", "suno/chirp_bluejay/text-to-music-simple", "suno/chirp_crow/get-audio-analysis", "suno/chirp_crow/get-clip-detail", "suno/chirp_crow/get-lyrics-timeline", "suno/chirp_crow/get-persona", "suno/chirp_crow/get-voice", "suno/chirp_crow/list-personas", "suno/chirp_crow/list-voices", "suno/chirp_crow/lyrics-pair", "suno/chirp_crow/query-songs", "suno/chirp_crow/recommend-styles", "suno/chirp_crow/text-to-lyrics", "suno/chirp_crow/text-to-music-simple", "suno/chirp_fenix/get-audio-analysis", "suno/chirp_fenix/get-clip-detail", "suno/chirp_fenix/get-lyrics-timeline", "suno/chirp_fenix/get-persona", "suno/chirp_fenix/get-voice", "suno/chirp_fenix/list-personas", "suno/chirp_fenix/list-voices", "suno/chirp_fenix/lyrics-pair", "suno/chirp_fenix/query-songs", "suno/chirp_fenix/recommend-styles", "suno/chirp_fenix/text-to-lyrics", "suno/chirp_fenix/text-to-music-simple", "suno/chirp_v4/get-audio-analysis", "suno/chirp_v4/get-clip-detail", "suno/chirp_v4/get-lyrics-timeline", "suno/chirp_v4/get-persona", "suno/chirp_v4/get-voice", "suno/chirp_v4/list-personas", "suno/chirp_v4/list-voices", "suno/chirp_v4/lyrics-pair", "suno/chirp_v4/query-songs", "suno/chirp_v4/recommend-styles", "suno/chirp_v4/text-to-lyrics", "suno/chirp_v4/text-to-music-simple" ], "examples": [ "gpt/gpt-4.1-mini/lyrics-generation", "gpt/gpt-4.1/lyrics-generation", "gpt/gpt-4o-mini/lyrics-generation", "gpt/gpt-4o/lyrics-generation", "mv/mv-managed-basic/generate-managed-mv" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "config": { "description": "Do not use a top-level config wrapper on generic /tasks; put priority/tags/metadata/webhookUrl at the top level.", "not": {} }, "inputParameters": { "description": "Input parameters for the task", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "model": { "default": "gpt/gpt-4.1-mini/lyrics-generation", "description": "Public model path in format \"providerCode/modelCode/featureCode\". Legacy Suno model names remain accepted and execute on their V6 equivalents while retaining the requested pricing identity.", "enum": [ "gpt/gpt-4.1-mini/lyrics-generation", "gpt/gpt-4.1/lyrics-generation", "gpt/gpt-4o-mini/lyrics-generation", "gpt/gpt-4o/lyrics-generation", "mv/mv-managed-basic/generate-managed-mv", "producer/lyria-3-5/generate-image", "producer/lyria-3-5/generate-lyrics", "producer/lyria-3-5/generate-music-compose", "producer/lyria-3-5/generate-music-modify", "producer/lyria-3-preview/generate-image", "producer/lyria-3-preview/generate-lyrics", "producer/lyria-3-preview/generate-music-compose", "producer/lyria-3-preview/generate-music-modify", "producer/lyria-3-pro/generate-image", "producer/lyria-3-pro/generate-lyrics", "producer/lyria-3-pro/generate-music-compose", "producer/lyria-3-pro/generate-music-modify", "suno/chirp-auk-turbo/get-audio-analysis", "suno/chirp-auk-turbo/get-clip-detail", "suno/chirp-auk-turbo/get-lyrics-timeline", "suno/chirp-auk-turbo/get-persona", "suno/chirp-auk-turbo/get-voice", "suno/chirp-auk-turbo/list-personas", "suno/chirp-auk-turbo/list-voices", "suno/chirp-auk-turbo/lyrics-pair", "suno/chirp-auk-turbo/query-songs", "suno/chirp-auk-turbo/recommend-styles", "suno/chirp-auk-turbo/text-to-lyrics", "suno/chirp-auk-turbo/text-to-music-simple", "suno/chirp-auk/get-audio-analysis", "suno/chirp-auk/get-clip-detail", "suno/chirp-auk/get-lyrics-timeline", "suno/chirp-auk/get-persona", "suno/chirp-auk/get-voice", "suno/chirp-auk/list-personas", "suno/chirp-auk/list-voices", "suno/chirp-auk/lyrics-pair", "suno/chirp-auk/query-songs", "suno/chirp-auk/recommend-styles", "suno/chirp-auk/text-to-lyrics", "suno/chirp-auk/text-to-music-simple", "suno/chirp-bluejay/get-audio-analysis", "suno/chirp-bluejay/get-clip-detail", "suno/chirp-bluejay/get-lyrics-timeline", "suno/chirp-bluejay/get-persona", "suno/chirp-bluejay/get-voice", "suno/chirp-bluejay/list-personas", "suno/chirp-bluejay/list-voices", "suno/chirp-bluejay/lyrics-pair", "suno/chirp-bluejay/query-songs", "suno/chirp-bluejay/recommend-styles", "suno/chirp-bluejay/text-to-lyrics", "suno/chirp-bluejay/text-to-music-simple", "suno/chirp-crow/get-audio-analysis", "suno/chirp-crow/get-clip-detail", "suno/chirp-crow/get-lyrics-timeline", "suno/chirp-crow/get-persona", "suno/chirp-crow/get-voice", "suno/chirp-crow/list-personas", "suno/chirp-crow/list-voices", "suno/chirp-crow/lyrics-pair", "suno/chirp-crow/query-songs", "suno/chirp-crow/recommend-styles", "suno/chirp-crow/text-to-lyrics", "suno/chirp-crow/text-to-music-simple", "suno/chirp-fenix/get-audio-analysis", "suno/chirp-fenix/get-clip-detail", "suno/chirp-fenix/get-lyrics-timeline", "suno/chirp-fenix/get-persona", "suno/chirp-fenix/get-voice", "suno/chirp-fenix/list-personas", "suno/chirp-fenix/list-voices", "suno/chirp-fenix/lyrics-pair", "suno/chirp-fenix/query-songs", "suno/chirp-fenix/recommend-styles", "suno/chirp-fenix/text-to-lyrics", "suno/chirp-fenix/text-to-music-simple", "suno/chirp-goose/get-audio-analysis", "suno/chirp-goose/get-clip-detail", "suno/chirp-goose/get-lyrics-timeline", "suno/chirp-goose/get-persona", "suno/chirp-goose/get-voice", "suno/chirp-goose/list-personas", "suno/chirp-goose/list-voices", "suno/chirp-goose/lyrics-pair", "suno/chirp-goose/query-songs", "suno/chirp-goose/recommend-styles", "suno/chirp-goose/text-to-lyrics", "suno/chirp-goose/text-to-music-simple", "suno/chirp-hawk-wild/get-audio-analysis", "suno/chirp-hawk-wild/get-clip-detail", "suno/chirp-hawk-wild/get-lyrics-timeline", "suno/chirp-hawk-wild/get-persona", "suno/chirp-hawk-wild/get-voice", "suno/chirp-hawk-wild/list-personas", "suno/chirp-hawk-wild/list-voices", "suno/chirp-hawk-wild/lyrics-pair", "suno/chirp-hawk-wild/query-songs", "suno/chirp-hawk-wild/recommend-styles", "suno/chirp-hawk-wild/text-to-lyrics", "suno/chirp-hawk-wild/text-to-music-simple", "suno/chirp-hawk/get-audio-analysis", "suno/chirp-hawk/get-clip-detail", "suno/chirp-hawk/get-lyrics-timeline", "suno/chirp-hawk/get-persona", "suno/chirp-hawk/get-voice", "suno/chirp-hawk/list-personas", "suno/chirp-hawk/list-voices", "suno/chirp-hawk/lyrics-pair", "suno/chirp-hawk/query-songs", "suno/chirp-hawk/recommend-styles", "suno/chirp-hawk/text-to-lyrics", "suno/chirp-hawk/text-to-music-simple", "suno/chirp-v4/get-audio-analysis", "suno/chirp-v4/get-clip-detail", "suno/chirp-v4/get-lyrics-timeline", "suno/chirp-v4/get-persona", "suno/chirp-v4/get-voice", "suno/chirp-v4/list-personas", "suno/chirp-v4/list-voices", "suno/chirp-v4/lyrics-pair", "suno/chirp-v4/query-songs", "suno/chirp-v4/recommend-styles", "suno/chirp-v4/text-to-lyrics", "suno/chirp-v4/text-to-music-simple", "suno/chirp_auk/get-audio-analysis", "suno/chirp_auk/get-clip-detail", "suno/chirp_auk/get-lyrics-timeline", "suno/chirp_auk/get-persona", "suno/chirp_auk/get-voice", "suno/chirp_auk/list-personas", "suno/chirp_auk/list-voices", "suno/chirp_auk/lyrics-pair", "suno/chirp_auk/query-songs", "suno/chirp_auk/recommend-styles", "suno/chirp_auk/text-to-lyrics", "suno/chirp_auk/text-to-music-simple", "suno/chirp_auk_turbo/get-audio-analysis", "suno/chirp_auk_turbo/get-clip-detail", "suno/chirp_auk_turbo/get-lyrics-timeline", "suno/chirp_auk_turbo/get-persona", "suno/chirp_auk_turbo/get-voice", "suno/chirp_auk_turbo/list-personas", "suno/chirp_auk_turbo/list-voices", "suno/chirp_auk_turbo/lyrics-pair", "suno/chirp_auk_turbo/query-songs", "suno/chirp_auk_turbo/recommend-styles", "suno/chirp_auk_turbo/text-to-lyrics", "suno/chirp_auk_turbo/text-to-music-simple", "suno/chirp_bluejay/get-audio-analysis", "suno/chirp_bluejay/get-clip-detail", "suno/chirp_bluejay/get-lyrics-timeline", "suno/chirp_bluejay/get-persona", "suno/chirp_bluejay/get-voice", "suno/chirp_bluejay/list-personas", "suno/chirp_bluejay/list-voices", "suno/chirp_bluejay/lyrics-pair", "suno/chirp_bluejay/query-songs", "suno/chirp_bluejay/recommend-styles", "suno/chirp_bluejay/text-to-lyrics", "suno/chirp_bluejay/text-to-music-simple", "suno/chirp_crow/get-audio-analysis", "suno/chirp_crow/get-clip-detail", "suno/chirp_crow/get-lyrics-timeline", "suno/chirp_crow/get-persona", "suno/chirp_crow/get-voice", "suno/chirp_crow/list-personas", "suno/chirp_crow/list-voices", "suno/chirp_crow/lyrics-pair", "suno/chirp_crow/query-songs", "suno/chirp_crow/recommend-styles", "suno/chirp_crow/text-to-lyrics", "suno/chirp_crow/text-to-music-simple", "suno/chirp_fenix/get-audio-analysis", "suno/chirp_fenix/get-clip-detail", "suno/chirp_fenix/get-lyrics-timeline", "suno/chirp_fenix/get-persona", "suno/chirp_fenix/get-voice", "suno/chirp_fenix/list-personas", "suno/chirp_fenix/list-voices", "suno/chirp_fenix/lyrics-pair", "suno/chirp_fenix/query-songs", "suno/chirp_fenix/recommend-styles", "suno/chirp_fenix/text-to-lyrics", "suno/chirp_fenix/text-to-music-simple", "suno/chirp_v4/get-audio-analysis", "suno/chirp_v4/get-clip-detail", "suno/chirp_v4/get-lyrics-timeline", "suno/chirp_v4/get-persona", "suno/chirp_v4/get-voice", "suno/chirp_v4/list-personas", "suno/chirp_v4/list-voices", "suno/chirp_v4/lyrics-pair", "suno/chirp_v4/query-songs", "suno/chirp_v4/recommend-styles", "suno/chirp_v4/text-to-lyrics", "suno/chirp_v4/text-to-music-simple" ], "examples": [ "gpt/gpt-4.1-mini/lyrics-generation", "gpt/gpt-4.1/lyrics-generation", "gpt/gpt-4o-mini/lyrics-generation", "gpt/gpt-4o/lyrics-generation", "mv/mv-managed-basic/generate-managed-mv" ], "type": "string" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "required": [ "model", "inputParameters" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsCharged": { "anyOf": [ { "description": "Exact credits actually charged", "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "creditsRequired": { "description": "Exact credits deducted to start the task", "minimum": 0, "type": "number" }, "errorCode": { "anyOf": [ { "description": "Error code if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "errorMessage": { "anyOf": [ { "description": "Error message if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "outputResults": { "anyOf": [ { "description": "Task output results" }, { "type": "null" } ], "nullable": true }, "pollUrl": { "anyOf": [ { "description": "Set only when the synchronous wait timed out (HTTP 202, status=PROCESSING). The task is still running — poll this URL for the final result. Null/absent on terminal responses.", "type": "string" }, { "type": "null" } ], "nullable": true }, "processingDuration": { "anyOf": [ { "description": "Processing duration in milliseconds", "type": "number" }, { "type": "null" } ], "nullable": true }, "processingDurationText": { "anyOf": [ { "description": "Human-readable processing duration, e.g. 16.2s", "type": "string" }, { "type": "null" } ], "nullable": true }, "resources": { "description": "Standardized resources produced by the task", "items": { "description": "A consumable resource produced by the task.", "properties": { "assetId": { "description": "Stable OmnAPI-owned asset id when available.", "type": "string" }, "assetStatus": { "enum": [ "READY", "EXPIRED", "DELETING", "DELETED" ], "type": "string" }, "byteLength": { "anyOf": [ { "description": "Resource size in bytes.", "type": "number" }, { "type": "null" } ], "nullable": true }, "content": { "anyOf": [ { "description": "Inline text content (e.g. lyrics).", "type": "string" }, { "type": "null" } ], "nullable": true }, "contentType": { "anyOf": [ { "description": "Resource content type.", "type": "string" }, { "type": "null" } ], "nullable": true }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "durationSec": { "anyOf": [ { "description": "Resource duration in seconds.", "type": "number" }, { "type": "null" } ], "nullable": true }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "id": { "description": "Stable resource id (OmnAPI resource id).", "type": "string" }, "index": { "description": "Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.", "minimum": 0, "type": "number" }, "metadata": { "anyOf": [ { "patternProperties": { "^(.*)$": {} }, "type": "object" }, { "type": "null" } ], "nullable": true }, "retainedUntil": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "role": { "enum": [ "candidate", "final", "stem", "fallback", "output" ], "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "enum": [ "MUSIC", "IMAGE", "VIDEO", "AUDIO", "TEXT", "METADATA" ], "type": "string" }, "url": { "anyOf": [ { "description": "Presigned/public URL.", "type": "string" }, { "type": "null" } ], "nullable": true }, "urlExpiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true } }, "required": [ "id", "index", "role", "type" ], "type": "object" }, "type": "array" }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "description": "Task unique identifier", "type": "string" } }, "required": [ "taskId", "status", "creditsRequired", "creditsCharged", "outputResults", "errorCode", "errorMessage", "processingDuration", "processingDurationText" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "creditsCharged": { "anyOf": [ { "description": "Exact credits actually charged", "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "creditsRequired": { "description": "Exact credits deducted to start the task", "minimum": 0, "type": "number" }, "errorCode": { "anyOf": [ { "description": "Error code if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "errorMessage": { "anyOf": [ { "description": "Error message if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "outputResults": { "anyOf": [ { "description": "Task output results" }, { "type": "null" } ], "nullable": true }, "pollUrl": { "anyOf": [ { "description": "Set only when the synchronous wait timed out (HTTP 202, status=PROCESSING). The task is still running — poll this URL for the final result. Null/absent on terminal responses.", "type": "string" }, { "type": "null" } ], "nullable": true }, "processingDuration": { "anyOf": [ { "description": "Processing duration in milliseconds", "type": "number" }, { "type": "null" } ], "nullable": true }, "processingDurationText": { "anyOf": [ { "description": "Human-readable processing duration, e.g. 16.2s", "type": "string" }, { "type": "null" } ], "nullable": true }, "resources": { "description": "Standardized resources produced by the task", "items": { "description": "A consumable resource produced by the task.", "properties": { "assetId": { "description": "Stable OmnAPI-owned asset id when available.", "type": "string" }, "assetStatus": { "enum": [ "READY", "EXPIRED", "DELETING", "DELETED" ], "type": "string" }, "byteLength": { "anyOf": [ { "description": "Resource size in bytes.", "type": "number" }, { "type": "null" } ], "nullable": true }, "content": { "anyOf": [ { "description": "Inline text content (e.g. lyrics).", "type": "string" }, { "type": "null" } ], "nullable": true }, "contentType": { "anyOf": [ { "description": "Resource content type.", "type": "string" }, { "type": "null" } ], "nullable": true }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "durationSec": { "anyOf": [ { "description": "Resource duration in seconds.", "type": "number" }, { "type": "null" } ], "nullable": true }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "id": { "description": "Stable resource id (OmnAPI resource id).", "type": "string" }, "index": { "description": "Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.", "minimum": 0, "type": "number" }, "metadata": { "anyOf": [ { "patternProperties": { "^(.*)$": {} }, "type": "object" }, { "type": "null" } ], "nullable": true }, "retainedUntil": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "role": { "enum": [ "candidate", "final", "stem", "fallback", "output" ], "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "enum": [ "MUSIC", "IMAGE", "VIDEO", "AUDIO", "TEXT", "METADATA" ], "type": "string" }, "url": { "anyOf": [ { "description": "Presigned/public URL.", "type": "string" }, { "type": "null" } ], "nullable": true }, "urlExpiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true } }, "required": [ "id", "index", "role", "type" ], "type": "object" }, "type": "array" }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "description": "Task unique identifier", "type": "string" } }, "required": [ "taskId", "status", "creditsRequired", "creditsCharged", "outputResults", "errorCode", "errorMessage", "processingDuration", "processingDurationText" ], "type": "object" } } }, "description": "Response for status 202", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403 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." }, "408": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 408" }, "413": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 413" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 422" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 502" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Create Task (Sync)", "tags": [ "Tasks" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tasks/{taskId}": { "get": { "description": "Get task details by ID", "operationId": "getApiV1TasksById", "parameters": [ { "in": "path", "name": "taskId", "required": true, "schema": { "description": "Task ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "actionRequired": { "anyOf": [ { "description": "Stable action the caller should take before retrying.", "type": "string" }, { "type": "null" } ], "nullable": true }, "createdAt": { "anyOf": [ { "description": "Task creation timestamp", "type": "Date" }, { "format": "date-time", "type": "string" }, { "format": "date", "type": "string" }, { "type": "number" } ], "description": "Task creation timestamp" }, "creditsCharged": { "anyOf": [ { "description": "Credits actually charged", "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "creditsRequired": { "description": "Credits deducted to start the task", "minimum": 0, "type": "number" }, "errorCode": { "anyOf": [ { "description": "Error code if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "errorMessage": { "anyOf": [ { "description": "Error message if task failed", "type": "string" }, { "type": "null" } ], "nullable": true }, "errorReason": { "anyOf": [ { "description": "Stable machine-readable reason for an actionable error.", "type": "string" }, { "type": "null" } ], "nullable": true }, "feature": { "anyOf": [ { "properties": { "code": { "description": "Feature code", "type": "string" }, "name": { "description": "Feature name", "type": "string" } }, "required": [ "name", "code" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "inputParameters": { "description": "Task input parameters" }, "metadata": { "anyOf": [ { "description": "Additional metadata" }, { "type": "null" } ], "nullable": true }, "model": { "anyOf": [ { "properties": { "code": { "description": "Model code", "type": "string" }, "name": { "description": "Model display name", "type": "string" }, "version": { "description": "Model version", "type": "string" } }, "required": [ "name", "code", "version" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "outputResults": { "anyOf": [ { "description": "Task output results" }, { "type": "null" } ], "nullable": true }, "pricing": { "anyOf": [ { "additionalProperties": false, "properties": { "components": { "items": { "additionalProperties": false, "properties": { "credits": { "description": "Final credits charged for this component.", "minimum": 0, "type": "number" }, "key": { "description": "Stable billing component key.", "type": "string" }, "label": { "description": "Human-readable component label.", "type": "string" } }, "required": [ "key", "label", "credits" ], "type": "object" }, "type": "array" }, "quoteVersion": { "description": "Pricing quote version stored with the task.", "minimum": 1, "type": "number" } }, "required": [ "quoteVersion", "components" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "processingCompletedAt": { "anyOf": [ { "anyOf": [ { "description": "Processing completion timestamp", "type": "Date" }, { "format": "date-time", "type": "string" }, { "format": "date", "type": "string" }, { "type": "number" } ], "description": "Processing completion timestamp" }, { "type": "null" } ], "nullable": true }, "processingDuration": { "anyOf": [ { "description": "Processing duration in milliseconds", "type": "number" }, { "type": "null" } ], "nullable": true }, "processingDurationText": { "anyOf": [ { "description": "Human-readable processing duration, e.g. 16.2s", "type": "string" }, { "type": "null" } ], "nullable": true }, "processingStartedAt": { "anyOf": [ { "anyOf": [ { "description": "Processing start timestamp", "type": "Date" }, { "format": "date-time", "type": "string" }, { "format": "date", "type": "string" }, { "type": "number" } ], "description": "Processing start timestamp" }, { "type": "null" } ], "nullable": true }, "product": { "anyOf": [ { "additionalProperties": false, "properties": { "finalUrl": { "anyOf": [ { "description": "Final downloadable asset URL when ready.", "type": "string" }, { "type": "null" } ], "nullable": true }, "mode": { "anyOf": [ { "description": "Product mode when applicable, e.g. fast or studio.", "type": "string" }, { "type": "null" } ], "nullable": true }, "mvId": { "anyOf": [ { "description": "Canonical MV id.", "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "description": "Product family for this task, e.g. mv.", "type": "string" }, "viewUrl": { "anyOf": [ { "description": "Product detail endpoint for this resource.", "type": "string" }, { "type": "null" } ], "nullable": true } }, "required": [ "type" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "progress": { "anyOf": [ { "description": "Task progress percentage (0-100)", "maximum": 100, "minimum": 0, "type": "number" }, { "type": "null" } ], "nullable": true }, "provider": { "anyOf": [ { "properties": { "code": { "description": "Provider code", "type": "string" }, "name": { "description": "Provider display name", "type": "string" } }, "required": [ "name", "code" ], "type": "object" }, { "type": "null" } ], "nullable": true }, "refunded": { "description": "Whether credits were refunded", "type": "boolean" }, "rejectedField": { "anyOf": [ { "description": "Input field that must be changed before a new task.", "type": "string" }, { "type": "null" } ], "nullable": true }, "resources": { "description": "Standardized resources produced by the task", "items": { "description": "A consumable resource produced by the task.", "properties": { "assetId": { "description": "Stable OmnAPI-owned asset id when available.", "type": "string" }, "assetStatus": { "enum": [ "READY", "EXPIRED", "DELETING", "DELETED" ], "type": "string" }, "byteLength": { "anyOf": [ { "description": "Resource size in bytes.", "type": "number" }, { "type": "null" } ], "nullable": true }, "content": { "anyOf": [ { "description": "Inline text content (e.g. lyrics).", "type": "string" }, { "type": "null" } ], "nullable": true }, "contentType": { "anyOf": [ { "description": "Resource content type.", "type": "string" }, { "type": "null" } ], "nullable": true }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "durationSec": { "anyOf": [ { "description": "Resource duration in seconds.", "type": "number" }, { "type": "null" } ], "nullable": true }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "id": { "description": "Stable resource id (OmnAPI resource id).", "type": "string" }, "index": { "description": "Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.", "minimum": 0, "type": "number" }, "metadata": { "anyOf": [ { "patternProperties": { "^(.*)$": {} }, "type": "object" }, { "type": "null" } ], "nullable": true }, "retainedUntil": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "role": { "enum": [ "candidate", "final", "stem", "fallback", "output" ], "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "enum": [ "MUSIC", "IMAGE", "VIDEO", "AUDIO", "TEXT", "METADATA" ], "type": "string" }, "url": { "anyOf": [ { "description": "Presigned/public URL.", "type": "string" }, { "type": "null" } ], "nullable": true }, "urlExpiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true } }, "required": [ "id", "index", "role", "type" ], "type": "object" }, "type": "array" }, "retryable": { "description": "Whether a new request may succeed after the reported terminal failure.", "type": "boolean" }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "tags": { "anyOf": [ { "description": "Structured task tags" }, { "type": "null" } ], "nullable": true }, "taskId": { "description": "Task unique identifier", "type": "string" }, "updatedAt": { "anyOf": [ { "description": "Last update timestamp", "type": "Date" }, { "format": "date-time", "type": "string" }, { "format": "date", "type": "string" }, { "type": "number" } ], "description": "Last update timestamp" }, "warningCodes": { "items": { "description": "Non-fatal terminal result warnings", "type": "string" }, "type": "array" }, "webhookUrl": { "anyOf": [ { "description": "Webhook callback URL", "type": "string" }, { "type": "null" } ], "nullable": true } }, "required": [ "taskId", "status", "progress", "outputResults", "warningCodes", "creditsRequired", "creditsCharged", "refunded", "retryable", "processingDuration", "processingDurationText", "errorCode", "errorMessage", "createdAt", "updatedAt", "processingStartedAt", "processingCompletedAt", "metadata" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Get Task", "tags": [ "Tasks" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tasks/{taskId}/cancel": { "post": { "description": "Cancel a task before Provider submission, or after submission only when its Provider confirms remote cancellation. Unconfirmed post-submit tasks remain active and return 409.", "operationId": "postApiV1TasksByIdCancel", "parameters": [ { "in": "path", "name": "taskId", "required": true, "schema": { "description": "Task ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "message": { "description": "Result message", "type": "string" }, "success": { "description": "Whether cancellation succeeded", "type": "boolean" }, "taskId": { "description": "Cancelled task identifier", "type": "string" } }, "required": [ "success", "message", "taskId" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 409" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "Cancel Task", "tags": [ "Tasks" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/tasks/{taskId}/stream": { "get": { "description": "Subscribe to real-time task status updates using Server-Sent Events (SSE). Receives updates without repeated status queries. Emits `connected` (initial snapshot), `update` (state change), `complete` (terminal), `reconnect` (deployment drain or bounded connection rotation), `error`, and `:ping` heartbeats every 25s.", "operationId": "getApiV1TasksByIdStream", "parameters": [ { "in": "path", "name": "taskId", "required": true, "schema": { "description": "Task ID", "type": "string" } } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "description": "Server-Sent Events stream.", "type": "string" } } }, "description": "SSE stream. Events: connected, update, complete, reconnect, and error; comment heartbeats are sent every 25 seconds.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Forbidden: the API key lacks the required scope or its IP policy rejects this request." }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" } }, "summary": "Stream Task Status (SSE)", "tags": [ "Tasks" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/usage/export": { "get": { "description": "Streams the caller's usage line items for a period as JSON (default) or CSV (?format=csv or Accept: text/csv). The range defaults to the last 30 days and may span at most 366 days. Requires the usage:read scope.", "operationId": "getApiV1UsageExport", "parameters": [ { "in": "query", "name": "startDate", "required": false, "schema": { "description": "ISO date (inclusive)", "type": "string" } }, { "in": "query", "name": "endDate", "required": false, "schema": { "description": "ISO date (inclusive)", "type": "string" } }, { "in": "query", "name": "apiKeyId", "required": false, "schema": { "description": "Restrict to one of the caller's API keys", "type": "string" } }, { "in": "query", "name": "format", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json", "description": "Response representation. Overrides the Accept header when supplied." } }, { "description": "Select JSON (default) or CSV. The format query parameter takes precedence when supplied.", "in": "header", "name": "Accept", "required": false, "schema": { "default": "application/json", "enum": [ "application/json", "text/csv" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "items": { "items": { "additionalProperties": false, "properties": { "apiKeyId": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "creditsUsed": { "type": "number" }, "endpoint": { "type": "string" }, "id": { "type": "string" }, "ipAddress": { "nullable": true, "type": "string" }, "method": { "type": "string" }, "responseTimeMs": { "type": "number" }, "statusCode": { "type": "integer" }, "userAgent": { "nullable": true, "type": "string" } }, "required": [ "id", "apiKeyId", "endpoint", "method", "statusCode", "responseTimeMs", "creditsUsed", "ipAddress", "userAgent", "createdAt" ], "type": "object" }, "type": "array" } }, "required": [ "items" ], "type": "object" } }, "text/csv": { "schema": { "description": "UTF-8 CSV with a header row followed by usage records.", "type": "string" } } }, "description": "Usage records streamed in the requested representation.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" } }, "summary": "Export usage records (self-serve)", "tags": [ "Usage" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/vidu/quote": { "post": { "description": "Returns the customer charge at 2.0 OmnAPI credits per Vidu credit. MV-specific commercial rates never apply. No media is downloaded or inspected.", "operationId": "postApiV1ViduQuote", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "input": { "description": "Selected Vidu Enterprise v2 request body. Use public http(s) media URLs only. callback_url and callbackUrl are rejected; use config.webhookUrl on task creation. The complete operation-by-operation field index and nested shapes are documented at https://docs.omnapi.com/guides/vidu/#complete-input-field-index.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "operation": { "description": "Allowlisted Vidu operation. OmnAPI maps this value to a fixed Vidu endpoint; arbitrary paths are never accepted.", "enum": [ "image-to-video", "reference-to-video", "start-end-to-video", "text-to-video", "reference-to-image", "text-to-audio", "timing-to-audio", "text-to-speech", "voice-clone", "lip-sync", "motion-sync-v1", "motion-sync-v2", "extend-video", "multi-frame-video", "upscale-video", "replace-video", "digital-human", "prompt-recommendation", "template", "template-story", "general-film-create", "general-film-edit", "general-film-compose", "ad-film-create", "ad-film-edit", "ad-film-compose", "trending-replicate" ], "type": "string" }, "pricingContext": { "additionalProperties": false, "properties": { "durationSec": { "description": "Billing duration for URL-only media operations. OmnAPI does not download or probe the media.", "exclusiveMinimum": 0, "maximum": 3600, "type": "number" }, "providerCreditCap": { "description": "Vidu-credit authorization reserve for operations without a deterministic published rate card.", "maximum": 100000, "minimum": 1, "multipleOf": 1, "type": "number" } }, "type": "object", "description": "Additional caller-supplied inputs required to calculate price." } }, "required": [ "operation", "input" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "input": { "description": "Selected Vidu Enterprise v2 request body. Use public http(s) media URLs only. callback_url and callbackUrl are rejected; use config.webhookUrl on task creation. The complete operation-by-operation field index and nested shapes are documented at https://docs.omnapi.com/guides/vidu/#complete-input-field-index.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "operation": { "description": "Allowlisted Vidu operation. OmnAPI maps this value to a fixed Vidu endpoint; arbitrary paths are never accepted.", "enum": [ "image-to-video", "reference-to-video", "start-end-to-video", "text-to-video", "reference-to-image", "text-to-audio", "timing-to-audio", "text-to-speech", "voice-clone", "lip-sync", "motion-sync-v1", "motion-sync-v2", "extend-video", "multi-frame-video", "upscale-video", "replace-video", "digital-human", "prompt-recommendation", "template", "template-story", "general-film-create", "general-film-edit", "general-film-compose", "ad-film-create", "ad-film-edit", "ad-film-compose", "trending-replicate" ], "type": "string" }, "pricingContext": { "additionalProperties": false, "properties": { "durationSec": { "description": "Billing duration for URL-only media operations. OmnAPI does not download or probe the media.", "exclusiveMinimum": 0, "maximum": 3600, "type": "number" }, "providerCreditCap": { "description": "Vidu-credit authorization reserve for operations without a deterministic published rate card.", "maximum": 100000, "minimum": 1, "multipleOf": 1, "type": "number" } }, "type": "object", "description": "Additional caller-supplied inputs required to calculate price." } }, "required": [ "operation", "input" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "input": { "description": "Selected Vidu Enterprise v2 request body. Use public http(s) media URLs only. callback_url and callbackUrl are rejected; use config.webhookUrl on task creation. The complete operation-by-operation field index and nested shapes are documented at https://docs.omnapi.com/guides/vidu/#complete-input-field-index.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "operation": { "description": "Allowlisted Vidu operation. OmnAPI maps this value to a fixed Vidu endpoint; arbitrary paths are never accepted.", "enum": [ "image-to-video", "reference-to-video", "start-end-to-video", "text-to-video", "reference-to-image", "text-to-audio", "timing-to-audio", "text-to-speech", "voice-clone", "lip-sync", "motion-sync-v1", "motion-sync-v2", "extend-video", "multi-frame-video", "upscale-video", "replace-video", "digital-human", "prompt-recommendation", "template", "template-story", "general-film-create", "general-film-edit", "general-film-compose", "ad-film-create", "ad-film-edit", "ad-film-compose", "trending-replicate" ], "type": "string" }, "pricingContext": { "additionalProperties": false, "properties": { "durationSec": { "description": "Billing duration for URL-only media operations. OmnAPI does not download or probe the media.", "exclusiveMinimum": 0, "maximum": 3600, "type": "number" }, "providerCreditCap": { "description": "Vidu-credit authorization reserve for operations without a deterministic published rate card.", "maximum": 100000, "minimum": 1, "multipleOf": 1, "type": "number" } }, "type": "object", "description": "Additional caller-supplied inputs required to calculate price." } }, "required": [ "operation", "input" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "credits": { "type": "number" }, "customerRate": { "const": 2, "type": "number" }, "notes": { "items": { "type": "string" }, "type": "array" }, "operation": { "description": "Allowlisted Vidu operation. OmnAPI maps this value to a fixed Vidu endpoint; arbitrary paths are never accepted.", "enum": [ "image-to-video", "reference-to-video", "start-end-to-video", "text-to-video", "reference-to-image", "text-to-audio", "timing-to-audio", "text-to-speech", "voice-clone", "lip-sync", "motion-sync-v1", "motion-sync-v2", "extend-video", "multi-frame-video", "upscale-video", "replace-video", "digital-human", "prompt-recommendation", "template", "template-story", "general-film-create", "general-film-edit", "general-film-compose", "ad-film-create", "ad-film-edit", "ad-film-compose", "trending-replicate" ], "type": "string" }, "pricingMode": { "enum": [ "rate-card", "authorization-cap" ], "type": "string" }, "pricingVersion": { "type": "string" }, "publicUsd": { "type": "number" }, "viduCredits": { "type": "number" } }, "required": [ "operation", "viduCredits", "credits", "publicUsd", "pricingMode", "pricingVersion", "customerRate" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Forbidden: the API key lacks the required scope or its IP policy rejects this request." }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Quote a Vidu Direct operation", "tags": [ "Vidu Direct" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/vidu/tasks": { "post": { "description": "Relays an allowlisted Vidu operation through OmnAPI's Task/Credits lifecycle. Inputs and output URLs are passed through; OmnAPI does not upload, download, transcode, persist, or otherwise process media. Download outputs within one hour because finished URLs may expire sooner than standard 24-hour creation URLs.", "operationId": "postApiV1ViduTasks", "parameters": [ { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "input": { "description": "Selected Vidu Enterprise v2 request body. Use public http(s) media URLs only. callback_url and callbackUrl are rejected; use config.webhookUrl on task creation. The complete operation-by-operation field index and nested shapes are documented at https://docs.omnapi.com/guides/vidu/#complete-input-field-index.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "maxCredits": { "description": "Optional OmnAPI-credit ceiling checked before direct debit.", "minimum": 1, "type": "number" }, "operation": { "description": "Allowlisted Vidu operation. OmnAPI maps this value to a fixed Vidu endpoint; arbitrary paths are never accepted.", "enum": [ "image-to-video", "reference-to-video", "start-end-to-video", "text-to-video", "reference-to-image", "text-to-audio", "timing-to-audio", "text-to-speech", "voice-clone", "lip-sync", "motion-sync-v1", "motion-sync-v2", "extend-video", "multi-frame-video", "upscale-video", "replace-video", "digital-human", "prompt-recommendation", "template", "template-story", "general-film-create", "general-film-edit", "general-film-compose", "ad-film-create", "ad-film-edit", "ad-film-compose", "trending-replicate" ], "type": "string" }, "pricingContext": { "additionalProperties": false, "properties": { "durationSec": { "description": "Billing duration for URL-only media operations. OmnAPI does not download or probe the media.", "exclusiveMinimum": 0, "maximum": 3600, "type": "number" }, "providerCreditCap": { "description": "Vidu-credit authorization reserve for operations without a deterministic published rate card.", "maximum": 100000, "minimum": 1, "multipleOf": 1, "type": "number" } }, "type": "object", "description": "Additional caller-supplied inputs required to calculate price." } }, "required": [ "operation", "input" ], "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "input": { "description": "Selected Vidu Enterprise v2 request body. Use public http(s) media URLs only. callback_url and callbackUrl are rejected; use config.webhookUrl on task creation. The complete operation-by-operation field index and nested shapes are documented at https://docs.omnapi.com/guides/vidu/#complete-input-field-index.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "maxCredits": { "description": "Optional OmnAPI-credit ceiling checked before direct debit.", "minimum": 1, "type": "number" }, "operation": { "description": "Allowlisted Vidu operation. OmnAPI maps this value to a fixed Vidu endpoint; arbitrary paths are never accepted.", "enum": [ "image-to-video", "reference-to-video", "start-end-to-video", "text-to-video", "reference-to-image", "text-to-audio", "timing-to-audio", "text-to-speech", "voice-clone", "lip-sync", "motion-sync-v1", "motion-sync-v2", "extend-video", "multi-frame-video", "upscale-video", "replace-video", "digital-human", "prompt-recommendation", "template", "template-story", "general-film-create", "general-film-edit", "general-film-compose", "ad-film-create", "ad-film-edit", "ad-film-compose", "trending-replicate" ], "type": "string" }, "pricingContext": { "additionalProperties": false, "properties": { "durationSec": { "description": "Billing duration for URL-only media operations. OmnAPI does not download or probe the media.", "exclusiveMinimum": 0, "maximum": 3600, "type": "number" }, "providerCreditCap": { "description": "Vidu-credit authorization reserve for operations without a deterministic published rate card.", "maximum": 100000, "minimum": 1, "multipleOf": 1, "type": "number" } }, "type": "object", "description": "Additional caller-supplied inputs required to calculate price." } }, "required": [ "operation", "input" ], "type": "object" } }, "multipart/form-data": { "schema": { "additionalProperties": false, "properties": { "config": { "properties": { "metadata": { "description": "Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "priority": { "default": 5, "description": "Task priority 1-10 (higher = sooner). Default 5.", "examples": [ 1, 5, 10 ], "maximum": 10, "minimum": 1, "type": "number" }, "tags": { "description": "Free-form labels for filtering. Up to 20, 100 chars each.", "items": { "maxLength": 100, "type": "string" }, "maxItems": 20, "type": "array" }, "webhookUrl": { "description": "URL to receive task.* lifecycle events via the central webhook service.", "examples": [ "https://example.com/webhook" ], "format": "uri", "type": "string" } }, "type": "object", "description": "Standard task configuration: priority, tags, metadata, and webhookUrl." }, "input": { "description": "Selected Vidu Enterprise v2 request body. Use public http(s) media URLs only. callback_url and callbackUrl are rejected; use config.webhookUrl on task creation. The complete operation-by-operation field index and nested shapes are documented at https://docs.omnapi.com/guides/vidu/#complete-input-field-index.", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "maxCredits": { "description": "Optional OmnAPI-credit ceiling checked before direct debit.", "minimum": 1, "type": "number" }, "operation": { "description": "Allowlisted Vidu operation. OmnAPI maps this value to a fixed Vidu endpoint; arbitrary paths are never accepted.", "enum": [ "image-to-video", "reference-to-video", "start-end-to-video", "text-to-video", "reference-to-image", "text-to-audio", "timing-to-audio", "text-to-speech", "voice-clone", "lip-sync", "motion-sync-v1", "motion-sync-v2", "extend-video", "multi-frame-video", "upscale-video", "replace-video", "digital-human", "prompt-recommendation", "template", "template-story", "general-film-create", "general-film-edit", "general-film-compose", "ad-film-create", "ad-film-edit", "ad-film-compose", "trending-replicate" ], "type": "string" }, "pricingContext": { "additionalProperties": false, "properties": { "durationSec": { "description": "Billing duration for URL-only media operations. OmnAPI does not download or probe the media.", "exclusiveMinimum": 0, "maximum": 3600, "type": "number" }, "providerCreditCap": { "description": "Vidu-credit authorization reserve for operations without a deterministic published rate card.", "maximum": 100000, "minimum": 1, "multipleOf": 1, "type": "number" } }, "type": "object", "description": "Additional caller-supplied inputs required to calculate price." } }, "required": [ "operation", "input" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "creditsRequired": { "type": "number" }, "pollUrl": { "type": "string" }, "pricingMode": { "enum": [ "rate-card", "authorization-cap" ], "type": "string" }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "type": "string" }, "viduCredits": { "type": "number" } }, "required": [ "taskId", "status", "creditsRequired", "viduCredits", "pricingMode", "pollUrl" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "402": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 402" }, "403": { "content": { "application/json": { "examples": { "paymentReview": { "value": { "error": { "code": "FORBIDDEN", "details": { "billingHoldReason": null, "paymentDebtCredits": 0, "reason": "PAYMENT_REVERSAL_DEBT" }, "message": "Billing account is on hold pending payment review or payment reversal resolution" }, "success": false } } }, "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "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." }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 409" }, "413": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 413" }, "429": { "$ref": "#/components/responses/OmnapiTaskRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 502" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Create a Vidu Direct task", "tags": [ "Vidu Direct" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/vidu/tasks/{id}": { "get": { "description": "Returns OmnAPI task state and pass-through Vidu resource URLs. The published one-hour window is conservative: standard creation URLs may last 24 hours, while finished outputs may expire sooner.", "operationId": "getApiV1ViduTasksById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Vidu task identifier returned by task creation." } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "output": {}, "outputUrlTtlHours": { "const": 1, "description": "Conservative download window. Some Vidu creation URLs remain valid for 24 hours, but finished outputs may expire after 1 hour.", "type": "number" }, "progress": { "maximum": 100, "minimum": 0, "type": "number" }, "resources": { "items": { "description": "A consumable resource produced by the task.", "properties": { "assetId": { "description": "Stable OmnAPI-owned asset id when available.", "type": "string" }, "assetStatus": { "enum": [ "READY", "EXPIRED", "DELETING", "DELETED" ], "type": "string" }, "byteLength": { "anyOf": [ { "description": "Resource size in bytes.", "type": "number" }, { "type": "null" } ], "nullable": true }, "content": { "anyOf": [ { "description": "Inline text content (e.g. lyrics).", "type": "string" }, { "type": "null" } ], "nullable": true }, "contentType": { "anyOf": [ { "description": "Resource content type.", "type": "string" }, { "type": "null" } ], "nullable": true }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "durationSec": { "anyOf": [ { "description": "Resource duration in seconds.", "type": "number" }, { "type": "null" } ], "nullable": true }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true }, "id": { "description": "Stable resource id (OmnAPI resource id).", "type": "string" }, "index": { "description": "Stable zero-based provider result slot. Finalized post-process resources may use a higher reserved slot.", "minimum": 0, "type": "number" }, "metadata": { "anyOf": [ { "patternProperties": { "^(.*)$": {} }, "type": "object" }, { "type": "null" } ], "nullable": true }, "retainedUntil": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "role": { "enum": [ "candidate", "final", "stem", "fallback", "output" ], "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "nullable": true }, "type": { "enum": [ "MUSIC", "IMAGE", "VIDEO", "AUDIO", "TEXT", "METADATA" ], "type": "string" }, "url": { "anyOf": [ { "description": "Presigned/public URL.", "type": "string" }, { "type": "null" } ], "nullable": true }, "urlExpiresAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "nullable": true }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "nullable": true } }, "required": [ "id", "index", "role", "type" ], "type": "object" }, "type": "array" }, "status": { "default": "PENDING", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" }, "taskId": { "type": "string" } }, "required": [ "taskId", "status", "progress", "outputUrlTtlHours" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Get a Vidu Direct task", "tags": [ "Vidu Direct" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/vidu/tasks/{id}/cancel": { "post": { "description": "Before submission, cancellation is local and refundable. After submission, OmnAPI calls Vidu's cancellation endpoint and refunds only when Vidu explicitly confirms cancellation.", "operationId": "postApiV1ViduTasksByIdCancel", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Vidu task identifier returned by task creation." } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "success": { "type": "boolean" }, "taskId": { "type": "string" } }, "required": [ "success", "message", "taskId" ], "type": "object" } } }, "description": "Response for status 200", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Policy": { "$ref": "#/components/headers/X-RateLimit-Policy" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Scope": { "$ref": "#/components/headers/X-RateLimit-Scope" }, "X-RateLimit-Type": { "$ref": "#/components/headers/X-RateLimit-Type" } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 400" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 401" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 403" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 404" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 409" }, "429": { "$ref": "#/components/responses/OmnapiCustomerRateLimited" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 500" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 502" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "description": "Application-specific error code (see error catalog)", "type": "string" }, "details": { "description": "Additional error details (optional)", "patternProperties": { "^(.*)$": {} }, "type": "object" }, "message": { "description": "Human readable error message", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "description": "Always false for error responses", "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Response for status 503" } }, "summary": "Cancel a Vidu Direct task", "tags": [ "Vidu Direct" ], "security": [ { "ApiKeyAuth": [] } ] } } }, "servers": [ { "url": "https://api.omnapi.com", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Producer", "description": "Image, lyrics, and music generation through OmnAPI Producer." }, { "name": "Lyrics", "description": "Structured lyrics generation for music and MV workflows." }, { "name": "Suno", "description": "Suno-compatible music generation and task workflows." }, { "name": "MV", "description": "Music video creation, preflight, quoting, and finalization workflows." }, { "name": "Subtitles", "description": "Lyrics and subtitle timing extraction workflows." }, { "name": "Vidu Direct", "description": "Vidu video, image, audio, template, and one-click solution workflows." }, { "name": "Tasks", "description": "Shared task polling endpoints for asynchronous public APIs." }, { "name": "Pricing", "description": "Public credit pricing catalog." }, { "name": "Account", "description": "Authenticated account balance and billing status." }, { "name": "Usage", "description": "Authenticated usage export for reporting and reconciliation." } ] }