Job

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/tunova-ai/json-schema/tunova-ai-job-schema.json",
  "title": "Job",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/tunova-ai-openapi.json#/components/schemas/Job",
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "processing",
        "submitted",
        "complete",
        "failed"
      ]
    },
    "phase": {
      "type": "string",
      "enum": [
        "streaming",
        "delivering"
      ],
      "description": "streaming: transient previews available; delivering: provider finished, validated audio is being stored. Status remains submitted until delivery completes."
    },
    "clips": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Clip"
      }
    },
    "preview_clips": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Clip"
      },
      "description": "Currently playable expected tracks; this may initially contain only the first track while its sibling is still rendering. Never treat previews as the authoritative final result; replace them with clips when status becomes complete."
    },
    "preview_at": {
      "type": "integer",
      "description": "Unix time when the first playable expected track was observed"
    },
    "lyrics": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": true,
      "description": "Present for a standalone `/api/lyrics` job"
    },
    "error": {
      "type": [
        "string",
        "null"
      ]
    },
    "created_at": {
      "type": "integer"
    },
    "updated_at": {
      "type": "integer"
    }
  },
  "$defs": {
    "Clip": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "audio_url": {
          "type": "string",
          "format": "uri"
        },
        "image_url": {
          "type": "string",
          "format": "uri",
          "description": "Cover art"
        },
        "title": {
          "type": "string"
        },
        "model": {
          "type": "string",
          "description": "Actual model reported by Suno (v6 for new v6/v5.5 generations; historical results retain their original model)"
        },
        "tags": {
          "type": "string",
          "description": "Style / genre tags"
        },
        "duration": {
          "type": "number",
          "description": "Seconds"
        }
      }
    }
  }
}