Naar inhoud springen
API-referentie
API-referentie

Suno muziek inspireren

Gebruik het eindpunt voor inspirerende muziek om een asynchrone taak aan te maken.

Markdown bekijken
01

Overzicht

Gebruik het eindpunt voor inspirerende muziek met een ondersteund model. Gebruik de geretourneerde taak-ID om de status op te halen, of geef callback_url op voor de hieronder gedocumenteerde leveringen.

Snelstart

  1. Maak een API-sleutel aan en stel deze in als RUNAPI_API_KEY.
  2. Kies een ondersteund model en stuur een POST-verzoek waarvan de body overeenkomt met het schema van dat model.
  3. Sla de geretourneerde taak-ID op en poll vervolgens totdat een eindstatus is bereikt, of verwerk de hieronder gedocumenteerde callbacks.

Eindpunt

POST /api/v1/suno/inspire_music
Basis-URL
https://runapi.ai
API-versie
v1
Authenticatie
Authorization: Bearer YOUR_API_TOKEN
02

Ondersteunde modellen

Open een modelpagina voor actuele prijzen, snelheidslimieten en details over commercieel gebruik.

03

Verzoekschema

JSON-body

Velden en toegestane waarden zijn afhankelijk van het geselecteerde model. Indien opgegeven, ontvangt callback_url de hieronder gedocumenteerde taakaflevering.

suno-v43 velden
audio_urlsarray
Verplicht

Eén tot vier audio-URL's die de nieuwe muziek sturen.

Itembereik: 1 - 4
callback_urlstring
Optioneel

Webhook-URL voor asynchrone meldingen.

modelstring
Verplicht

Model-slug.

suno-v4.53 velden
audio_urlsarray
Verplicht

Eén tot vier audio-URL's die de nieuwe muziek sturen.

Itembereik: 1 - 4
callback_urlstring
Optioneel

Webhook-URL voor asynchrone meldingen.

modelstring
Verplicht

Model-slug.

suno-v4.5-plus3 velden
audio_urlsarray
Verplicht

Eén tot vier audio-URL's die de nieuwe muziek sturen.

Itembereik: 1 - 4
callback_urlstring
Optioneel

Webhook-URL voor asynchrone meldingen.

modelstring
Verplicht

Model-slug.

suno-v53 velden
audio_urlsarray
Verplicht

Eén tot vier audio-URL's die de nieuwe muziek sturen.

Itembereik: 1 - 4
callback_urlstring
Optioneel

Webhook-URL voor asynchrone meldingen.

modelstring
Verplicht

Model-slug.

suno-v5.53 velden
audio_urlsarray
Verplicht

Eén tot vier audio-URL's die de nieuwe muziek sturen.

Itembereik: 1 - 4
callback_urlstring
Optioneel

Webhook-URL voor asynchrone meldingen.

modelstring
Verplicht

Model-slug.

04

Acceptatie aanmaken

HTTP 202

POST /api/v1/suno/inspire_music

Responsschema
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    },
    "task_replayed": {
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "status",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Responsvoorbeeld

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "status": "processing"
}
05

Pollen bezig

HTTP 200

GET /api/v1/suno/inspire_music/:id

Responsschema
JSON 
{
  "properties": {
    "audios": {
      "items": {
        "properties": {
          "audio_url": {
            "type": "string",
            "x-runapi-generated-media": true
          },
          "duration": {
            "type": "number"
          },
          "id": {
            "type": "string"
          },
          "image_url": {
            "type": "string",
            "x-runapi-generated-media": true
          },
          "lyrics": {
            "type": "string"
          },
          "model_name": {
            "type": "string"
          },
          "stream_audio_url": {
            "type": "string",
            "x-runapi-generated-media": true
          },
          "tags": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "title": {
            "type": "string"
          }
        },
        "required": [
          "id"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    },
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "generation_stage": {
      "enum": [
        "text_generated",
        "first_audio_ready"
      ],
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Responsvoorbeeld

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "generation_stage": "text_generated",
  "id": "tsk_reference_demo",
  "status": "processing"
}
06

Pollen voltooid

HTTP 200

GET /api/v1/suno/inspire_music/:id

Responsschema
JSON 
{
  "properties": {
    "audios": {
      "items": {
        "properties": {
          "audio_url": {
            "type": "string",
            "x-runapi-generated-media": true
          },
          "duration": {
            "type": "number"
          },
          "id": {
            "type": "string"
          },
          "image_url": {
            "type": "string",
            "x-runapi-generated-media": true
          },
          "lyrics": {
            "type": "string"
          },
          "model_name": {
            "type": "string"
          },
          "stream_audio_url": {
            "type": "string",
            "x-runapi-generated-media": true
          },
          "tags": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "title": {
            "type": "string"
          }
        },
        "required": [
          "id"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    },
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "generation_stage": {
      "enum": [
        "text_generated",
        "first_audio_ready",
        "all_audios_ready",
        "failed"
      ],
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "audios",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Responsvoorbeeld

JSON 
{
  "audios": [
    {
      "audio_url": "https://file.runapi.ai/reference-audio.mp3",
      "id": "audio_reference"
    }
  ],
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "status": "completed"
}
07

Pollen mislukt

HTTP 200

GET /api/v1/suno/inspire_music/:id

Responsschema
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "error": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error",
    "billing"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Responsvoorbeeld

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "error": "Task processing failed.",
  "id": "tsk_reference_demo",
  "status": "failed"
}
08

Callback van klant: wordt verwerkt

HTTP 200

POST callback_url

Responsschema
JSON 
{
  "properties": {
    "audios": {
      "items": {
        "properties": {
          "audio_url": {
            "type": "string",
            "x-runapi-generated-media": true
          },
          "duration": {
            "type": "number"
          },
          "id": {
            "type": "string"
          },
          "image_url": {
            "type": "string",
            "x-runapi-generated-media": true
          },
          "lyrics": {
            "type": "string"
          },
          "model_name": {
            "type": "string"
          },
          "stream_audio_url": {
            "type": "string",
            "x-runapi-generated-media": true
          },
          "tags": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "title": {
            "type": "string"
          }
        },
        "required": [
          "id"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    },
    "generation_stage": {
      "enum": [
        "text_generated",
        "first_audio_ready"
      ],
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "processing"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Responsvoorbeeld

JSON 
{
  "generation_stage": "text_generated",
  "id": "tsk_reference_demo",
  "status": "processing"
}
09

Callback van klant: voltooid

HTTP 200

POST callback_url

Responsschema
JSON 
{
  "properties": {
    "audios": {
      "items": {
        "properties": {
          "audio_url": {
            "type": "string",
            "x-runapi-generated-media": true
          },
          "duration": {
            "type": "number"
          },
          "id": {
            "type": "string"
          },
          "image_url": {
            "type": "string",
            "x-runapi-generated-media": true
          },
          "lyrics": {
            "type": "string"
          },
          "model_name": {
            "type": "string"
          },
          "stream_audio_url": {
            "type": "string",
            "x-runapi-generated-media": true
          },
          "tags": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "title": {
            "type": "string"
          }
        },
        "required": [
          "id"
        ],
        "type": "object",
        "unevaluatedProperties": false
      },
      "type": "array"
    },
    "generation_stage": {
      "enum": [
        "text_generated",
        "first_audio_ready",
        "all_audios_ready",
        "failed"
      ],
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "audios"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Responsvoorbeeld

JSON 
{
  "audios": [
    {
      "audio_url": "https://file.runapi.ai/reference-audio.mp3",
      "id": "audio_reference"
    }
  ],
  "id": "tsk_reference_demo",
  "status": "completed"
}
10

Callback van klant: mislukt

HTTP 200

POST callback_url

Responsschema
JSON 
{
  "properties": {
    "error": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "properties": {
            "code": {
              "type": "string"
            },
            "limit_cents": {
              "type": "integer"
            },
            "message": {
              "type": "string"
            },
            "reset_at": {
              "format": "date-time",
              "type": [
                "string",
                "null"
              ]
            },
            "used_cents": {
              "type": "integer"
            },
            "window": {
              "enum": [
                "1h",
                "1d",
                "7d",
                "daily",
                "weekly",
                "monthly",
                "lifetime"
              ],
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "type": "object",
          "unevaluatedProperties": false
        }
      ]
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "failed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Responsvoorbeeld

JSON 
{
  "error": {
    "code": "generation_failed",
    "message": "Task processing failed."
  },
  "id": "tsk_reference_demo",
  "status": "failed"
}
11

Fouten

HTTP 401

POST /api/v1/suno/inspire_music

Responsschema
JSON 
{
  "properties": {
    "error": {
      "description": "Leesbare foutmelding.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Responsvoorbeeld

JSON 
{
  "error": "Authentication required"
}
12

Fouten

HTTP 401

GET /api/v1/suno/inspire_music/:id

Responsschema
JSON 
{
  "properties": {
    "error": {
      "description": "Leesbare foutmelding.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Responsvoorbeeld

JSON 
{
  "error": "Authentication required"
}
13

Fouten

HTTP 400

POST /api/v1/suno/inspire_music

Responsschema
JSON 
{
  "oneOf": [
    {
      "properties": {
        "error": {
          "description": "Leesbare foutmelding.",
          "type": "string"
        }
      },
      "required": [
        "error"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    {
      "properties": {
        "error": {
          "description": "Leesbare validatiesamenvatting.",
          "type": "string"
        },
        "errors": {
          "additionalProperties": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "description": "Validatieberichten gekoppeld aan het openbare aanvraagveld, met een reeks leesbare tekenreeksen per veld.",
          "type": "object"
        }
      },
      "required": [
        "error",
        "errors"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  ]
}

Responsvoorbeeld

JSON 
{
  "error": "model must be one of: suno-v4, suno-v4.5, suno-v4.5-plus, suno-v5, suno-v5.5"
}
14

Fouten

HTTP 402

POST /api/v1/suno/inspire_music

Responsschema
JSON 
{
  "properties": {
    "error": {
      "description": "Leesbare foutmelding.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Responsvoorbeeld

JSON 
{
  "error": "Insufficient balance"
}
15

Fouten

HTTP 429

POST /api/v1/suno/inspire_music

Responsschema
JSON 
{
  "properties": {
    "error": {
      "description": "Leesbare foutmelding.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Responsvoorbeeld

JSON 
{
  "error": "API key credit limit exceeded"
}
16

Fouten

HTTP 409

POST /api/v1/suno/inspire_music

Responsschema
JSON 
{
  "properties": {
    "error": {
      "description": "Leesbare foutmelding.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Responsvoorbeeld

JSON 
{
  "error": "The request uses features that are not supported for the selected model"
}
17

Fouten

HTTP 429

POST /api/v1/suno/inspire_music

Responsschema
JSON 
{
  "properties": {
    "error": {
      "description": "Leesbare foutmelding.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Responsvoorbeeld

JSON 
{
  "error": "Rate limit reached. Please retry later."
}
18

Fouten

HTTP 503

POST /api/v1/suno/inspire_music

Responsschema
JSON 
{
  "properties": {
    "error": {
      "description": "Leesbare foutmelding.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Responsvoorbeeld

JSON 
{
  "error": "Service under maintenance, please try again later"
}
19

Fouten

HTTP 504

POST /api/v1/suno/inspire_music

Responsschema
JSON 
{
  "properties": {
    "error": {
      "description": "Leesbare foutmelding.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Responsvoorbeeld

JSON 
{
  "error": "The request timed out"
}
20

Fouten

HTTP 404

GET /api/v1/suno/inspire_music/:id

Responsschema
JSON 
{
  "properties": {
    "error": {
      "description": "Leesbare foutmelding.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Responsvoorbeeld

JSON 
{
  "error": "Task with id 'tsk_reference_demo' not found"
}
21

Gegenereerde codevoorbeelden

Gebruik cURL rechtstreeks, of installeer een SDK voor uw taal. Elk voorbeeld dient het gevalideerde verzoek in dat in deze referentie wordt getoond.

Installeren

Shell 
pip install runapi-suno
PYTHON 
import os
from runapi.suno import SunoClient

client = SunoClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.inspire_music.create(
  model="suno-v5",
  audio_urls=["https://file.runapi.ai/inspiration-one.mp3", "https://file.runapi.ai/inspiration-two.mp3"]
)