{
  "openapi": "3.1.0",
  "info": {
    "title": "Seed-Audio 1.0 오디오 생성 API",
    "description": "Seed-Audio 1.0 멀티모달 오디오 생성 API. 텍스트→오디오, 참조 오디오(음성 복제), 참조 이미지 세 가지 모드를 지원하며 요청당 최대 120초의 오디오를 생성합니다. 오디오북, 더빙, 게임 등에 적합합니다.",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.evolink.ai",
      "description": "프로덕션"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/audios/generations": {
      "post": {
        "summary": "Seed-Audio 1.0 오디오 생성",
        "description": "- 세 가지 모드의 멀티모달 오디오 생성: **텍스트→오디오**, **참조 오디오(음성 복제)**, **참조 이미지**\n- 요청당 최대 `120`초의 오디오\n- 비동기 모드 — 반환된 작업 ID로 [결과 조회](/ko/api-manual/task-management/get-task-detail)\n- 생성된 오디오 링크는 24시간 동안 유효하므로 즉시 저장하시기 바랍니다",
        "operationId": "createSeedAudio10",
        "tags": [
          "오디오 생성"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SeedAudioRequest"
              },
              "examples": {
                "basic": {
                  "summary": "텍스트→오디오",
                  "value": {
                    "model": "doubao-seed-audio-1-0",
                    "prompt": "오디오 생성 서비스에 오신 것을 환영합니다. 오늘 날씨가 참 좋네요.",
                    "format": "mp3"
                  }
                },
                "with_voice": {
                  "summary": "지정된 음성으로 생성",
                  "value": {
                    "model": "doubao-seed-audio-1-0",
                    "prompt": "여러분, 안녕하세요. 저녁 뉴스에 오신 것을 환영합니다.",
                    "audio_references": [
                      "zh_female_vv_uranus_bigtts"
                    ],
                    "speech_rate": 1.25
                  }
                },
                "voice_clone": {
                  "summary": "참조 오디오 생성(음성 복제)",
                  "value": {
                    "model": "doubao-seed-audio-1-0",
                    "prompt": "@오디오1 안녕하세요, 만나서 반갑습니다.",
                    "audio_references": [
                      "https://example.com/ref-voice.mp3"
                    ]
                  }
                },
                "multi_voice": {
                  "summary": "혼합 음성(음성 ID + 오디오 URL)",
                  "value": {
                    "model": "doubao-seed-audio-1-0",
                    "prompt": "@오디오1 안녕하세요! @오디오2 오늘 하루 어떠셨어요?",
                    "audio_references": [
                      "zh_female_vv_uranus_bigtts",
                      "https://example.com/ref-voice.mp3"
                    ]
                  }
                },
                "image_ref": {
                  "summary": "참조 이미지 생성",
                  "value": {
                    "model": "doubao-seed-audio-1-0",
                    "prompt": "이미지의 분위기에 어울리는 보이스오버를 합성합니다.",
                    "image_urls": [
                      "https://example.com/scene.jpg"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "오디오 생성 작업이 정상적으로 생성됨",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SeedAudioResponse"
                }
              }
            }
          },
          "400": {
            "description": "요청 파라미터가 잘못됨",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "code": "missing_text",
                    "message": "필수 파라미터 누락: prompt",
                    "type": "invalid_request_error"
                  }
                }
              }
            }
          },
          "401": {
            "description": "인증되지 않음; 토큰이 유효하지 않거나 만료됨",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "code": "unauthorized",
                    "message": "유효하지 않거나 만료된 토큰",
                    "type": "authentication_error"
                  }
                }
              }
            }
          },
          "402": {
            "description": "할당량 부족; 충전이 필요함",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "code": "insufficient_quota",
                    "message": "할당량이 부족합니다. 계정을 충전해 주세요.",
                    "type": "insufficient_quota"
                  }
                }
              }
            }
          },
          "403": {
            "description": "접근 권한 없음",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "code": "model_access_denied",
                    "message": "토큰에 모델 접근 권한이 없음: doubao-seed-audio-1-0",
                    "type": "invalid_request_error"
                  }
                }
              }
            }
          },
          "429": {
            "description": "요청 제한 초과",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "code": "rate_limit_exceeded",
                    "message": "요청이 너무 많습니다. 잠시 후 다시 시도해 주세요",
                    "type": "rate_limit_error"
                  }
                }
              }
            }
          },
          "500": {
            "description": "서버 내부 오류",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "code": "internal_error",
                    "message": "서버 내부 오류",
                    "type": "api_error"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SeedAudioRequest": {
        "type": "object",
        "required": [
          "model",
          "prompt"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "모델 이름",
            "enum": [
              "doubao-seed-audio-1-0"
            ],
            "default": "doubao-seed-audio-1-0",
            "example": "doubao-seed-audio-1-0"
          },
          "prompt": {
            "type": "string",
            "description": "오디오로 합성할 프롬프트 또는 텍스트\n\n**세 가지 생성 모드(전달된 참조 리소스에 따라 자동 감지됨):**\n- **텍스트→오디오**: `prompt`만 전달하여 프롬프트에서 직접 오디오 생성\n- **참조 오디오(음성 복제)**: `audio_references`와 함께 사용; 리터럴 마커 `@오디오N`로 N번째 항목 참조(배열 순서대로 `1`부터 번호 매김)\n- **참조 이미지**: `image_urls`와 함께 사용; `prompt`에는 합성할 텍스트만 입력\n\n> 오디오 참조(`audio_references`)와 이미지 참조(`image_urls`)는 **상호 배타적**이며, 요청당 하나만 사용할 수 있습니다.\n\n**제약 사항:**\n- 최대 `1500`자",
            "maxLength": 1500,
            "example": "오디오 생성 서비스에 오신 것을 환영합니다. 오늘 날씨가 참 좋네요."
          },
          "audio_references": {
            "type": "array",
            "description": "참조 리소스 목록. 각 항목은 **음성 ID** 또는 **참조 오디오 URL**일 수 있으며, 동일한 배열 안에서 두 유형을 **혼합**할 수 있습니다\n\n- **음성 ID**: 프리셋 음성의 `voice_type` — 전체 목록은 [Seed-Audio 1.0 음성 목록](/ko/api-manual/audio-series/doubao-seed-audio/doubao-seed-audio-1-0-voices) 참고\n- **오디오 URL**: 음성 복제용 참조 오디오 클립 업로드\n- **`image_urls`와 상호 배타적**: 참조 오디오와 참조 이미지는 둘 중 하나만 선택할 수 있으며, 하나의 요청에서 함께 보낼 수 없습니다\n- `prompt`에서 리터럴 마커 `@오디오N`로 N번째 항목 참조(배열 순서대로 `1`부터 번호 매김)\n- 생략 시 모델이 `prompt`를 기반으로 자유롭게 음성을 생성합니다\n\n**수량 제한:**\n- 배열 전체 최대 `3`개 항목(음성 ID와 오디오 URL 합산)\n\n**오디오 URL 제약 사항:**\n- 각 참조 클립 ≤ `30`초 및 ≤ `10 MB`\n- 포맷: `wav` / `mp3` / `pcm` / `ogg_opus`",
            "items": {
              "type": "string"
            },
            "maxItems": 3,
            "example": [
              "zh_female_vv_uranus_bigtts"
            ]
          },
          "image_urls": {
            "type": "array",
            "description": "참조 이미지 URL 목록; 이미지의 분위기에 맞는 오디오를 생성합니다\n\n- 이미지 참조 사용 시 `prompt`에는 합성할 텍스트만 입력\n- **`audio_references`와 상호 배타적**: 참조 이미지와 참조 오디오는 둘 중 하나만 선택할 수 있으며, 하나의 요청에서 함께 보낼 수 없습니다\n\n**제약 사항:**\n- 현재 `1`개 이미지만 지원, ≤ `10 MB`\n- 포맷: `jpeg` / `png` / `webp`",
            "items": {
              "type": "string",
              "format": "uri"
            },
            "maxItems": 1,
            "example": [
              "https://example.com/scene.jpg"
            ]
          },
          "format": {
            "type": "string",
            "description": "출력 오디오 포맷",
            "enum": [
              "wav",
              "mp3",
              "pcm",
              "ogg_opus"
            ],
            "default": "wav",
            "example": "mp3"
          },
          "sample_rate": {
            "type": "integer",
            "description": "출력 샘플 레이트(Hz)",
            "enum": [
              8000,
              16000,
              24000,
              32000,
              44100,
              48000
            ],
            "default": 24000,
            "example": 24000
          },
          "speech_rate": {
            "type": "number",
            "description": "속도 배율(소수점 둘째 자리까지 지원)\n\n- `1.0`: 기본 속도(기본값)\n- `2.0`: 2배속; `0.5`: 절반 속도\n\n범위 `0.5` ~ `2.0`",
            "minimum": 0.5,
            "maximum": 2,
            "multipleOf": 0.01,
            "default": 1,
            "example": 1.25
          },
          "loudness_rate": {
            "type": "number",
            "description": "음량 배율(소수점 둘째 자리까지 지원)\n\n- `1.0`: 기본 음량(기본값)\n- `2.0`: 2배 음량; `0.5`: 절반 음량\n\n범위 `0.5` ~ `2.0`",
            "minimum": 0.5,
            "maximum": 2,
            "multipleOf": 0.01,
            "default": 1,
            "example": 0.85
          },
          "pitch_rate": {
            "type": "integer",
            "description": "피치 조정, **반음 단위**\n\n- `0`: 기본 피치(변경 없음)\n- **양수 값은 피치를 높임**: 값이 클수록 음성이 더 높고 날카로워짐; `12`는 한 옥타브 높임\n- **음수 값은 피치를 낮춤**: 값이 작을수록 음성이 더 낮고 깊어짐; `-12`는 한 옥타브 낮춤\n\n범위 `-12` ~ `12`",
            "minimum": -12,
            "maximum": 12,
            "default": 0,
            "example": 0
          },
          "callback_url": {
            "type": "string",
            "description": "작업 완료 시 호출되는 HTTPS 콜백 URL\n\n**호출 시점:**\n- 작업이 완료, 실패 또는 취소될 때 트리거됨\n- 정산 완료 후 전송됨\n\n**보안 제한:**\n- HTTPS만 지원\n- 내부 IP 주소로의 콜백은 금지됨(127.0.0.1, 10.x.x.x, 172.16-31.x.x, 192.168.x.x 등)\n- URL 길이는 `2048`자를 초과할 수 없음\n\n**콜백 메커니즘:**\n- 타임아웃: `10`초\n- 실패 시 최대 `3`회 재시도(각 실패 후 `1` / `2` / `4`초)\n- 콜백 본문은 작업 조회 응답과 동일한 포맷\n- 2xx 응답은 성공으로 처리; 다른 상태 코드는 재시도를 트리거",
            "format": "uri",
            "example": "https://your-domain.com/webhooks/audio-completed"
          }
        }
      },
      "SeedAudioResponse": {
        "type": "object",
        "properties": {
          "created": {
            "type": "integer",
            "description": "작업 생성 타임스탬프",
            "example": 1775200000
          },
          "id": {
            "type": "string",
            "description": "작업 ID",
            "example": "task-unified-1775200000-abcd1234"
          },
          "model": {
            "type": "string",
            "description": "실제 사용된 모델",
            "example": "doubao-seed-audio-1-0"
          },
          "object": {
            "type": "string",
            "enum": [
              "audio.generation.task"
            ],
            "description": "구체적인 작업 타입"
          },
          "progress": {
            "type": "integer",
            "description": "작업 진행률 백분율(0-100)",
            "minimum": 0,
            "maximum": 100,
            "example": 0
          },
          "status": {
            "type": "string",
            "description": "작업 상태",
            "enum": [
              "pending",
              "processing",
              "completed",
              "failed"
            ],
            "example": "pending"
          },
          "task_info": {
            "$ref": "#/components/schemas/AudioTaskInfo",
            "description": "상세 오디오 작업 정보"
          },
          "type": {
            "type": "string",
            "enum": [
              "audio"
            ],
            "description": "작업 출력 타입",
            "example": "audio"
          },
          "usage": {
            "$ref": "#/components/schemas/AudioUsage",
            "description": "사용량 및 청구 정보"
          }
        }
      },
      "AudioTaskInfo": {
        "type": "object",
        "properties": {
          "can_cancel": {
            "type": "boolean",
            "description": "작업 취소 가능 여부",
            "example": true
          },
          "estimated_time": {
            "type": "integer",
            "description": "완료까지의 예상 시간(초)",
            "minimum": 0,
            "example": 15
          },
          "audio_type": {
            "type": "string",
            "description": "오디오 작업 타입",
            "example": "audio_generation"
          }
        }
      },
      "AudioUsage": {
        "type": "object",
        "description": "사용량 정보",
        "properties": {
          "credits_reserved": {
            "type": "number",
            "description": "예상 소비 크레딧(최대 지속 시간으로 예약, 작업 완료 시 실제 지속 시간으로 정산)",
            "minimum": 0,
            "example": 9.6
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "오류 코드 식별자"
              },
              "message": {
                "type": "string",
                "description": "오류 설명"
              },
              "type": {
                "type": "string",
                "description": "오류 타입"
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "##모든 엔드포인트는 Bearer Token 인증이 필요합니다##\n\n**API Key 발급:**\n\n[API Key 관리 페이지](https://evolink.ai/dashboard/keys)를 방문하여 API Key를 발급받으세요\n\n**요청 헤더에 추가:**\n```\nAuthorization: Bearer YOUR_API_KEY\n```"
      }
    }
  },
  "tags": [
    {
      "name": "오디오 생성",
      "description": "Seed-Audio 1.0 오디오 생성 엔드포인트"
    }
  ]
}