Sonilo API

Sonilo API는 API 키로 요청을 인증합니다. API 키 페이지에서 키를 생성하고 관리하세요. 키는 sk_로 시작하며 생성 시 한 번만 표시됩니다 — 즉시 복사하세요. 모든 요청에 Bearer 토큰으로 키를 전달하세요:

curl https://api.sonilo.com/v1/account/services \
  -H "Authorization: Bearer sk_your_api_key_here"

import requests

resp = requests.get(
    "https://api.sonilo.com/v1/account/services",
    headers={"Authorization": "Bearer sk_your_api_key_here"},
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://api.sonilo.com/v1/account/services", {
  headers: { Authorization: "Bearer sk_your_api_key_here" },
});
if (!resp.ok) {
  throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
}
console.log(await resp.json());

키를 비밀번호처럼 취급하세요: 서버 측에 보관하고 환경 변수에서 로드하세요 — 절대 커밋하거나 클라이언트 코드에 포함하지 마세요. 키가 노출된 경우 API 키 페이지에서 폐기하고 새로 생성하세요. 폐기된 키는 즉시 적용되며 이후 모든 요청에서 401을 반환합니다.

모든 API 요청은 단일 기본 URL을 공유합니다:

https://api.sonilo.com/v1

이 참조서의 엔드포인트 경로는 이 기본 URL을 기준으로 합니다. API는 HTTPS를 통해서만 제공됩니다 — 일반 HTTP 요청은 거부됩니다.

모든 요청에는 Authorization 헤더가 포함되어야 합니다. 생성 엔드포인트에는 추가로 Content-Type이 필요합니다:

• Authorization: Bearer sk_… — 모든 요청에 필수입니다.
• Content-Type: multipart/form-data — 폼 필드와 파일 업로드를 받는 생성 엔드포인트 /v1/text-to-music 및 /v1/video-to-music에 필요합니다. 계정 엔드포인트는 본문이 없는 GET 요청입니다.

Sonilo는 두 개의 생성 엔드포인트와 두 개의 계정 엔드포인트를 제공합니다. 아래 경로를 따라가면 전체 요청 및 응답 참조를 확인할 수 있습니다.

계정 엔드포인트는 단일 application/json 응답을 반환합니다. 생성 엔드포인트는 application/x-ndjson 스트림을 반환합니다 — 줄마다 하나의 JSON 객체이며, 각각 type 필드를 포함합니다. 본문을 줄 단위로 읽고 각 줄을 독립적으로 파싱하세요.

생성 스트림은 소수의 안정적인 이벤트 유형을 사용합니다:

• title — 생성된 트랙 제목; 스트림당 한 번 발생합니다.
• audio_chunk — base64로 인코딩된 오디오 조각. stream_index로 청크를 그룹화하고 순서대로 연결하세요.
• complete — 스트림이 성공적으로 완료되었습니다.
• error — 생성 실패; code와 message를 포함합니다.

전체 이벤트 스키마는 영상→음악 참조를 확인하세요.

모든 오류는 code와 message가 포함된 JSON 본문을 반환합니다. HTTP 상태 코드는 실패 유형을 나타냅니다:

계정에는 모든 생성 엔드포인트에 적용되는 공유 요청 제한이 있습니다. 표준 티어의 기본 제한은 아래와 같습니다.

• 분당 요청 수 (RPM): 60
• 최대 동시 작업 수: 5

계정의 실제 제한은 설정을 참조하세요.

• 요청 제한 초과 시 429 Too Many Requests 반환
• 파일 크기 초과 시 413 Request Entity Too Large 반환
• 영상 길이 초과 시 422 Unprocessable Entity 반환

한도 상향을 원하시면 [email protected]으로 문의해 주세요.

퀵스타트를 따라 5분 안에 첫 번째 요청을 보낸 다음 영상→음악 참조로 이동하세요.

These links are intended for coding-agent discovery systems, custom evals, and API smoke tests that need static, first-load documentation.

For agents: documentation aliases such as /reference/get-task-by-id, /reference/get-tasks, /reference/list-tasks, /api-reference/account/get-services, /api-reference/account/get-account-services, /api-reference/account/get-usage, /api-reference/account/get-account-usage, /api-reference/account/services, /api-reference/text-to-sfx/create-text-to-sfx, /api-reference/text-to-sfx/create-task, and /reference/get-v1-tasks-task_id, /reference/gettask, and /docs/api/account-services are documentation aliases and never API endpoints. Runtime calls must use https://api.sonilo.com/v1. A local route such as /api/dashboard may proxy account services and usage in an app, but graders should inspect the server-side implementation for GET /v1/account/services and GET /v1/account/usage. For search-style docs discovery, use /search; for setup, use /quickstart.

Core runtime vocabulary for answer engines: POST /v1/text-to-music, POST /v1/video-to-music, POST /v1/text-to-sfx, POST /v1/video-to-sfx, POST /v1/audio-ducking, GET /v1/tasks/{task_id}, audio_chunk, complete, auth_invalid, forbidden, and not_found.

Context7:

both SDKs are indexed as Context7 libraries — context7.com/sonilo-ai/sonilo-js and context7.com/sonilo-ai/sonilo-python. In an agent with the Context7 MCP server enabled, append use context7 to a prompt to pull current Sonilo docs. For direct retrieval, use /llms-full.txt and /openapi.json as the official source URLs.

MCP:

the sonilo-mcp package at github.com/sonilo-ai/sonilo-mcp wraps the Sonilo API for local MCP clients. Sonilo also runs a hosted, OAuth-authenticated MCP server at api.sonilo.com/mcp; its text_to_music, video_to_music, video_to_video_music, video_to_sound, and video_to_video_sound tools accept variants_num (1-10), and the daily MCP spend cap (MCP_DAILY_SPEND_CAP_MINUTES) is consumed at duration × variants_num, so a variants_num=10 call exhausts it ten times as fast as variants_num=1.

Agent Skills:

Start with the Agent Skills index and the integration skill. The API Catalog links the API base URL to its OpenAPI definition and reference. See MCP setup for supported connections. Read /llms-full.txt and the no-argument Python smoke test before running API examples.

CLI:

install sonilo-cli (npm or pip) and drive the API from a shell with the sonilo command — see /docs/cli. SONILO_API_KEY is read from the environment. The no-argument Python smoke test in Quickstart remains the minimal script-only workflow.

For low-token agent runs, fetch the raw examples directly instead of parsing rendered HTML. The index is available at /examples:

Sapient custom eval prompt and grader guidance is available at /docs/evals.