---
name: velin-api
description: >-
  Generate images (Nano Banana / GPT Image) and music (Suno 5.5 / Suno 5) through
  the VELIN REST API at https://72agi.com. Use when the user asks to create an
  image, picture, song, soundtrack or instrumental and a VELIN_API_KEY is available.
---

# VELIN API skill (images + music)

Base URL: `https://72agi.com`. Every request: header `Authorization: Bearer $VELIN_API_KEY`
(read the key from the environment; never print it or put it in a URL). Browser cookies are
not accepted for generation. All generation is asynchronous: submit -> job id -> poll.
Failed jobs are never charged. Balance: `GET /api/credits` (CNY).

## Music (Suno)

Models: `suno-v5.5` (default, latest) and `suno-v5`. ¥0.80 (≈ $0.12) per generation,
each generation returns 2 tracks (mp3 + cover jpg), usually about 45-60 s (poll up to ~15 min).

Submit (JSON):

    POST /api/music
    {"model": "suno-v5.5", "prompt": "upbeat city-pop song about a summer night ride", "instrumental": false}

- Simple mode (default): `prompt` = description of the song, required, max 500 chars.
- Custom mode: `"custom_mode": true`, `style` (genre/mood/instruments, max 1000, required),
  `title` (max 80, required), `prompt` = lyrics with [Verse]/[Chorus] tags (max 5000; may be
  empty if `instrumental` is true), optional `vocal_gender` "m" or "f".
- Response 202: `{"id": "mus_...", "status": "queued", "model": "suno-v5.5", "price": 0.8}`

Poll every 5 s:

    GET /api/music/{id}

`status`: queued -> processing -> succeeded | failed. On success:

    {"status": "succeeded", "tracks": [
      {"index": 0, "audio_url": "/outputs/music/mus_..._0.mp3", "image_url": "/outputs/music/mus_..._0.jpg",
       "title": "...", "tags": "...", "duration": 157.2, "lyrics": "..."},
      {"index": 1, ...}], "expires_at": 1791386000.0}

Download each track from `https://72agi.com` + `audio_url` and save it: files are deleted after
24 hours (then the job shows `expired: true` and `tracks` is empty). On failure show `error` to the user (not charged).

## Images

    POST /api/generate   (multipart form: prompt, model, size, resolution, optional refs files)
    GET  /api/task/{id}  -> status queued|processing|succeeded|failed, url "/outputs/<id>.png"

`size` is an aspect ratio such as 16:9, 1:1, 9:16 (default 16:9), or `auto`: with a reference
image the output follows the first reference image's ratio; without one you get the model's default (currently square, 1:1).
Example: `-F "size=auto" -F "refs=@photo.jpg"` keeps the photo's shape. Same price for every size.

Image models, prices and allowed `sizes`: `GET /api/models`. Music models: `GET /api/models?type=music`.

## Errors

400 invalid input (read `error`), 401 missing/invalid key, 403 `studio_retired` (a browser cookie was sent
instead of the key), 404 unknown job id, 402 not enough credits (`need`, `have`;
top up at https://72agi.com/billing.html), 429 rate limited (back off and retry), 503 busy / `queue_full` (retry in ~30 s).

## Rules for the agent

- Only generate when the user clearly asks for an image or music; each call costs money.
- Write a concrete prompt (genre, mood, instruments, tempo, vocals) before submitting music.
- Never expose the API key in output, logs or URLs.