# gcui-art/suno-api architecture

> Architecture diagram of the GitHub repository gcui-art/suno-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gcui-art/suno-api
- Repository: https://github.com/gcui-art/suno-api

## Overview

Suno AI API is a Next.js service that exposes Suno music-generation and related capabilities through HTTP endpoints, using a Suno account cookie for upstream access. The principal workflow is a caller submitting a generation request, its route invoking the Suno client, and the route returning the result; callers can then query or transform generated audio through separate endpoints. The README also documents OpenAI-compatible access, custom generation, lyrics, stems, extensions, and documentation UI. CAPTCHA handling and account keep-alive are described or visible in the client, though excerpts do not expose every internal call path.

Main entry points: [`src/lib/SunoApi.ts`](https://github.com/gcui-art/suno-api/blob/main/src/lib/SunoApi.ts) (Suno API client), [`src/app/api/generate/route.ts`](https://github.com/gcui-art/suno-api/blob/main/src/app/api/generate/route.ts) (Generate music), [`src/app/api/custom_generate/route.ts`](https://github.com/gcui-art/suno-api/blob/main/src/app/api/custom_generate/route.ts) (Custom generation), [`src/app/v1/chat/completions/route.ts`](https://github.com/gcui-art/suno-api/blob/main/src/app/v1/chat/completions/route.ts) (Chat completions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Creation APIs"]
  node_generate["Generate music<br/>[route.ts]"]
  node_custom["Custom generation<br/>[route.ts]"]
  node_chat["Chat completions<br/>[route.ts]"]
  node_lyrics["Generate lyrics<br/>[route.ts]"]
end

subgraph group_media["Audio APIs"]
  node_extend["Extend audio<br/>[route.ts]"]
  node_stems["Generate stems<br/>[route.ts]"]
  node_concat["Concatenate audio<br/>[route.ts]"]
  node_lookup["Audio lookup<br/>[route.ts]"]
  node_clip["Clip lookup<br/>[route.ts]"]
  node_alignment["Lyric alignment<br/>[route.ts]"]
  node_persona["Persona lookup<br/>[route.ts]"]
  node_quota["Quota lookup<br/>[route.ts]"]
end

subgraph group_client["Suno Client"]
  node_client["Suno API client<br/>[SunoApi.ts]"]
  node_utils["Request utilities<br/>[utils.ts]"]
  node_browser["Browser CAPTCHA flow<br/>[SunoApi.ts]"]
end

subgraph group_web["Web Experience"]
  node_home["Home page<br/>[page.tsx]"]
  node_docs["API documentation<br/>[page.tsx]"]
  node_header["Site header<br/>[Header.tsx]"]
  node_logo["Site logo<br/>[Logo.tsx]"]
  node_section["Page section<br/>[Section.tsx]"]
  node_footer["Site footer<br/>[Footer.tsx]"]
  node_swagger["Swagger viewer<br/>[Swagger.tsx]"]
end

node_caller(("API caller"))
node_suno{{"Suno service"}}
node_captcha{{"2Captcha service"}}

node_caller -->|"requests"| node_generate
node_caller -->|"requests"| node_custom
node_caller -->|"requests"| node_chat
node_caller -->|"requests"| node_lyrics
node_caller -->|"requests"| node_extend
node_caller -->|"requests"| node_stems
node_caller -->|"requests"| node_concat
node_caller -->|"requests"| node_lookup
node_caller -->|"requests"| node_clip
node_caller -->|"requests"| node_alignment
node_caller -.->|"requests"| node_persona
node_caller -->|"requests"| node_quota
node_generate -->|"calls generate"| node_client
node_custom -->|"calls custom_generate"| node_client
node_chat -->|"calls SunoApi"| node_client
node_lyrics -->|"calls generateLyrics"| node_client
node_extend -->|"calls extendAudio"| node_client
node_stems -->|"calls generateStems"| node_client
node_concat -->|"calls concatenate"| node_client
node_lookup -->|"calls get"| node_client
node_clip -->|"calls clip lookup"| node_client
node_alignment -->|"calls alignment"| node_client
node_persona -->|"calls persona lookup"| node_client
node_quota -->|"calls quota lookup"| node_client
node_client -->|"uses helpers"| node_utils
node_client -->|"sends API requests"| node_suno
node_client -->|"launches"| node_browser
node_browser -->|"submits challenges"| node_captcha
node_home -->|"renders"| node_section
node_header -->|"renders"| node_logo

click node_generate "https://github.com/gcui-art/suno-api/blob/main/src/app/api/generate/route.ts"
click node_custom "https://github.com/gcui-art/suno-api/blob/main/src/app/api/custom_generate/route.ts"
click node_chat "https://github.com/gcui-art/suno-api/blob/main/src/app/v1/chat/completions/route.ts"
click node_lyrics "https://github.com/gcui-art/suno-api/blob/main/src/app/api/generate_lyrics/route.ts"
click node_extend "https://github.com/gcui-art/suno-api/blob/main/src/app/api/extend_audio/route.ts"
click node_stems "https://github.com/gcui-art/suno-api/blob/main/src/app/api/generate_stems/route.ts"
click node_concat "https://github.com/gcui-art/suno-api/blob/main/src/app/api/concat/route.ts"
click node_lookup "https://github.com/gcui-art/suno-api/blob/main/src/app/api/get/route.ts"
click node_clip "https://github.com/gcui-art/suno-api/blob/main/src/app/api/clip/route.ts"
click node_alignment "https://github.com/gcui-art/suno-api/blob/main/src/app/api/get_aligned_lyrics/route.ts"
click node_persona "https://github.com/gcui-art/suno-api/blob/main/src/app/api/persona/route.ts"
click node_quota "https://github.com/gcui-art/suno-api/blob/main/src/app/api/get_limit/route.ts"
click node_client "https://github.com/gcui-art/suno-api/blob/main/src/lib/SunoApi.ts"
click node_utils "https://github.com/gcui-art/suno-api/blob/main/src/lib/utils.ts"
click node_browser "https://github.com/gcui-art/suno-api/blob/main/src/lib/SunoApi.ts"
click node_home "https://github.com/gcui-art/suno-api/blob/main/src/app/page.tsx"
click node_docs "https://github.com/gcui-art/suno-api/blob/main/src/app/docs/page.tsx"
click node_header "https://github.com/gcui-art/suno-api/blob/main/src/app/components/Header.tsx"
click node_logo "https://github.com/gcui-art/suno-api/blob/main/src/app/components/Logo.tsx"
click node_section "https://github.com/gcui-art/suno-api/blob/main/src/app/components/Section.tsx"
click node_footer "https://github.com/gcui-art/suno-api/blob/main/src/app/components/Footer.tsx"
click node_swagger "https://github.com/gcui-art/suno-api/blob/main/src/app/components/Swagger.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_generate,node_custom,node_chat,node_lyrics toneBlue
class node_extend,node_stems,node_concat,node_lookup,node_clip,node_alignment,node_persona,node_quota toneAmber
class node_client,node_utils,node_browser,node_caller toneMint
class node_home,node_docs,node_header,node_logo,node_section,node_footer,node_swagger toneRose
class node_suno,node_captcha toneIndigo
```

## Components

### Creation APIs

- [Generate music](https://github.com/gcui-art/suno-api/blob/main/src/app/api/generate/route.ts): `src/app/api/generate/route.ts`
- [Custom generation](https://github.com/gcui-art/suno-api/blob/main/src/app/api/custom_generate/route.ts): `src/app/api/custom_generate/route.ts`
- [Chat completions](https://github.com/gcui-art/suno-api/blob/main/src/app/v1/chat/completions/route.ts): `src/app/v1/chat/completions/route.ts`
- [Generate lyrics](https://github.com/gcui-art/suno-api/blob/main/src/app/api/generate_lyrics/route.ts): `src/app/api/generate_lyrics/route.ts`

### Audio APIs

- [Extend audio](https://github.com/gcui-art/suno-api/blob/main/src/app/api/extend_audio/route.ts): `src/app/api/extend_audio/route.ts`
- [Generate stems](https://github.com/gcui-art/suno-api/blob/main/src/app/api/generate_stems/route.ts): `src/app/api/generate_stems/route.ts`
- [Concatenate audio](https://github.com/gcui-art/suno-api/blob/main/src/app/api/concat/route.ts): `src/app/api/concat/route.ts`
- [Audio lookup](https://github.com/gcui-art/suno-api/blob/main/src/app/api/get/route.ts): `src/app/api/get/route.ts`
- [Clip lookup](https://github.com/gcui-art/suno-api/blob/main/src/app/api/clip/route.ts): `src/app/api/clip/route.ts`
- [Lyric alignment](https://github.com/gcui-art/suno-api/blob/main/src/app/api/get_aligned_lyrics/route.ts): `src/app/api/get_aligned_lyrics/route.ts`
- [Persona lookup](https://github.com/gcui-art/suno-api/blob/main/src/app/api/persona/route.ts): `src/app/api/persona/route.ts`
- [Quota lookup](https://github.com/gcui-art/suno-api/blob/main/src/app/api/get_limit/route.ts): `src/app/api/get_limit/route.ts`

### Suno Client

- [Suno API client](https://github.com/gcui-art/suno-api/blob/main/src/lib/SunoApi.ts): `src/lib/SunoApi.ts`
- [Request utilities](https://github.com/gcui-art/suno-api/blob/main/src/lib/utils.ts): `src/lib/utils.ts`
- [Browser CAPTCHA flow](https://github.com/gcui-art/suno-api/blob/main/src/lib/SunoApi.ts): `src/lib/SunoApi.ts`

### Web Experience

- [Home page](https://github.com/gcui-art/suno-api/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [API documentation](https://github.com/gcui-art/suno-api/blob/main/src/app/docs/page.tsx): `src/app/docs/page.tsx`
- [Site header](https://github.com/gcui-art/suno-api/blob/main/src/app/components/Header.tsx): `src/app/components/Header.tsx`
- [Site logo](https://github.com/gcui-art/suno-api/blob/main/src/app/components/Logo.tsx): `src/app/components/Logo.tsx`
- [Page section](https://github.com/gcui-art/suno-api/blob/main/src/app/components/Section.tsx): `src/app/components/Section.tsx`
- [Site footer](https://github.com/gcui-art/suno-api/blob/main/src/app/components/Footer.tsx): `src/app/components/Footer.tsx`
- [Swagger viewer](https://github.com/gcui-art/suno-api/blob/main/src/app/components/Swagger.tsx): `src/app/components/Swagger.tsx`

### Other components

- **API caller**
- **Suno service**
- **2Captcha service**

## Connections

- API caller → Generate music: requests (evidence: `README.md`)
- API caller → Custom generation: requests (evidence: `README.md`)
- API caller → Chat completions: requests (evidence: `README.md`)
- API caller → Generate lyrics: requests (evidence: `README.md`)
- API caller → Extend audio: requests (evidence: `README.md`)
- API caller → Generate stems: requests (evidence: `README.md`)
- API caller → Concatenate audio: requests (evidence: `README.md`)
- API caller → Audio lookup: requests (evidence: `README.md`)
- API caller → Clip lookup: requests (evidence: `README.md`)
- API caller → Lyric alignment: requests (evidence: `README.md`)
- API caller → Persona lookup: requests
- API caller → Quota lookup: requests (evidence: `README.md`)
- Generate music → Suno API client: calls generate (evidence: `src/app/api/generate/route.ts`)
- Custom generation → Suno API client: calls custom_generate (evidence: `src/app/api/custom_generate/route.ts`)
- Chat completions → Suno API client: calls SunoApi (evidence: `src/app/v1/chat/completions/route.ts`)
- Generate lyrics → Suno API client: calls generateLyrics (evidence: `src/app/api/generate_lyrics/route.ts`)
- Extend audio → Suno API client: calls extendAudio (evidence: `src/app/api/extend_audio/route.ts`)
- Generate stems → Suno API client: calls generateStems (evidence: `src/app/api/generate_stems/route.ts`)
- Concatenate audio → Suno API client: calls concatenate (evidence: `src/app/api/concat/route.ts`)
- Audio lookup → Suno API client: calls get (evidence: `src/app/api/get/route.ts`)
- Clip lookup → Suno API client: calls clip lookup (evidence: `src/app/api/clip/route.ts`)
- Lyric alignment → Suno API client: calls alignment (evidence: `src/app/api/get_aligned_lyrics/route.ts`)
- Persona lookup → Suno API client: calls persona lookup (evidence: `src/app/api/persona/route.ts`)
- Quota lookup → Suno API client: calls quota lookup (evidence: `src/app/api/get_limit/route.ts`)
- Suno API client → Request utilities: uses helpers (evidence: `src/lib/SunoApi.ts`)
- Suno API client → Suno service: sends API requests (evidence: `src/lib/SunoApi.ts`)
- Suno API client → Browser CAPTCHA flow: launches (evidence: `src/lib/SunoApi.ts`)
- Browser CAPTCHA flow → 2Captcha service: submits challenges (evidence: `src/lib/SunoApi.ts`)
- Home page → Page section: renders (evidence: `src/app/page.tsx`)
- Site header → Site logo: renders (evidence: `src/app/components/Header.tsx`)
