> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-chore-sync-comfy-api-v2-spec.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Comfy Router에서 Seed Audio 1.0 Multilingual 사용하기

> Comfy Router를 통해 byteplus/seed-audio-1.0-multilingual을 호출하는 방법: endpoint, 요청 형태, 그리고 Router가 반환하는 응답.

BytePlus에서 Comfy Router로 제공하는 `byteplus/seed-audio-1.0-multilingual`의 API 레퍼런스입니다.

## 빠른 시작

[Comfy 워크스페이스](https://platform.comfy.org/profile/api-keys)에서 키를 생성하고 `COMFY_API_KEY`로 내보내세요. Python 및 TypeScript 스니펫은 Comfy SDK(`pip install comfy-sdk`, `npm install @comfyorg/sdk`)를 사용하며, cURL 스니펫은 동일한 호출을 원시 HTTP로 수행합니다.

**모델 ID:** `byteplus/seed-audio-1.0-multilingual`

**엔드포인트:** `POST https://api.comfy.org/v2/models/byteplus/seed-audio-1.0-multilingual`

<Tabs>
  <Tab title="Wait for the result">
    <CodeGroup>
      ```python Python theme={null}
      from comfy_sdk import Comfy

      # Reads COMFY_API_KEY from the environment.
      # The SDK automatically creates an idempotency key and reuses it for automatic retries.
      with Comfy() as client:
          result = client.models.run(
              "byteplus/seed-audio-1.0-multilingual",
              {
                  "audio_config": {
                      "format": "wav",
                      "sample_rate": 24000,
                  },
                  "text_prompt": "Hello from Comfy Router.",
              },
          )

      print(result)
      ```

      ```typescript TypeScript theme={null}
      import { comfy } from "@comfyorg/sdk";

      // Reads COMFY_API_KEY from the environment.
      // The SDK automatically creates an idempotency key and reuses it for automatic retries.
      const { data } = await comfy.models.run("byteplus/seed-audio-1.0-multilingual", {
        audio_config: {
          format: "wav",
          sample_rate: 24000,
        },
        text_prompt: "Hello from Comfy Router.",
      });

      console.log(data);
      ```

      ```bash cURL theme={null}
      curl https://api.comfy.org/v2/models/byteplus/seed-audio-1.0-multilingual \
        -H "X-API-Key: $COMFY_API_KEY" \
        -H "Idempotency-Key: $(uuidgen)" \
        -H "Content-Type: application/json" \
        -d "{\"audio_config\": {\"format\":\"wav\",\"sample_rate\":24000}, \"text_prompt\": \"Hello from Comfy Router.\"}"
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Queue and collect later">
    <CodeGroup>
      ```python Python theme={null}
      from comfy_sdk import Comfy

      # Reads COMFY_API_KEY from the environment.
      # Each submit() call mints its own Idempotency-Key and reuses it for automatic retries.
      with Comfy() as client:
          handle = client.models.submit(
              "byteplus/seed-audio-1.0-multilingual",
              {
                  "audio_config": {
                      "format": "wav",
                      "sample_rate": 24000,
                  },
                  "text_prompt": "Hello from Comfy Router.",
              },
          )
          print("request_id:", handle.request_id)  # with the model ID, all another process needs

          # Poll until the request completes, waiting the Retry-After the server names.
          for update in handle.iter_events():
              print(update.status, update.queue_position)

          # The provider's own payload, the same value models.run() returns.
          # A request that failed or was cancelled raises the typed Router error here.
          result = handle.get()

      print(result)
      ```

      ```typescript TypeScript theme={null}
      import { comfy } from "@comfyorg/sdk";

      // Reads COMFY_API_KEY from the environment.
      // Each submit() call mints its own Idempotency-Key and reuses it for automatic retries.
      const handle = await comfy.models.submit("byteplus/seed-audio-1.0-multilingual", {
        audio_config: {
          format: "wav",
          sample_rate: 24000,
        },
        text_prompt: "Hello from Comfy Router.",
      });
      console.log("requestId:", handle.requestId); // with the model ID, all another process needs

      // Poll until the request completes, waiting the Retry-After the server names.
      for await (const update of handle.events()) {
        console.log(update.status, update.queuePosition);
      }

      // The same result models.run() returns. A request that failed or was cancelled rejects here.
      const result = await handle.get();

      console.log(result.data);
      ```

      ```bash cURL theme={null}
      # 1. Submit. Router answers 201 with request_id, status_url, response_url and cancel_url.
      curl https://api.comfy.org/v2/models/byteplus/seed-audio-1.0-multilingual/requests \
        -H "X-API-Key: $COMFY_API_KEY" \
        -H "Idempotency-Key: $(uuidgen)" \
        -H "Content-Type: application/json" \
        -d "{\"audio_config\": {\"format\":\"wav\",\"sample_rate\":24000}, \"text_prompt\": \"Hello from Comfy Router.\"}"

      # 2. Poll until status is COMPLETED, waiting the Retry-After seconds each response names.
      REQUEST_ID="<request_id from the 201 body>"
      curl -i https://api.comfy.org/v2/models/byteplus/seed-audio-1.0-multilingual/requests/$REQUEST_ID/status \
        -H "X-API-Key: $COMFY_API_KEY"

      # 3. Collect. 200 with the model's native output, 202 with the status body while it is still running.
      curl https://api.comfy.org/v2/models/byteplus/seed-audio-1.0-multilingual/requests/$REQUEST_ID \
        -H "X-API-Key: $COMFY_API_KEY"
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## 스키마

### 입력

<ParamField body="audio_config" type="object">
  출력 오디오 구성입니다.
</ParamField>

<ParamField body="audio_config.enable_subtitle" type="boolean">
  자막 서비스를 사용할지 여부입니다. 사용하면 응답에 발화 및 단어 수준 타임스탬프가 포함됩니다 (기본값: false).
</ParamField>

<ParamField body="audio_config.format" type="string">
  출력 오디오 형식: wav(기본값), mp3, pcm 또는 ogg\_opus.

  가능한 값: `wav`, `mp3`, `pcm`, `ogg_opus`
</ParamField>

<ParamField body="audio_config.loudness_rate" type="integer">
  -50에서 100까지이며, 100은 2.0배 볼륨, -50은 0.5배 볼륨을 의미합니다 (기본값: 0).

  범위: `-50` \~ `100`
</ParamField>

<ParamField body="audio_config.pitch_rate" type="integer">
  -12에서 12까지입니다 (기본값: 0).

  범위: `-12` \~ `12`
</ParamField>

<ParamField body="audio_config.sample_rate" type="integer">
  출력 샘플 레이트: 8000, 16000, 24000(기본값), 32000, 44100 또는 48000.

  가능한 값: `8000`, `16000`, `24000`, `32000`, `44100`, `48000`
</ParamField>

<ParamField body="audio_config.speech_rate" type="integer">
  -50에서 100까지이며, 100은 2.0배 속도, -50은 0.5배 속도를 의미합니다 (기본값: 0).

  범위: `-50` \~ `100`
</ParamField>

<ParamField body="model" type="string">
  모델 식별자입니다. 지원 모델: seed-audio-1.0 및 seed-audio-1.0-multilingual. POST /proxy/byteplus/api/v3/tts/create에 대한 직접 v1 호출은 반드시 이 값을 제공해야 합니다. 프록시는 다른 값이나 누락된 값에 대해 400으로 거부합니다. 이 스키마의 `required` 목록에 없는 이유는 Comfy Router가 /v2/models/byteplus/\{model}의 `{model}` 경로 세그먼트에서 이 값을 채우므로 Router 호출자는 이를 생략하기 때문입니다.
</ParamField>

<ParamField body="references" type="object[]">
  참조 리소스입니다. 텍스트 전용 생성에는 생략하세요. 최대 3개의 오디오 참조(각각 최대 30초, 디코딩 시 10 MB, wav, mp3, pcm 또는 ogg\_opus) 또는 정확히 1개의 이미지 참조(디코딩 시 최대 10 MB, jpeg, png 또는 webp)를 사용할 수 있습니다. 이미지 참조는 오디오 참조와 혼합할 수 없습니다. 이러한 상한은 BytePlus의 것이며, 디코딩된 바이트 기준으로 명시됩니다. base64는 자산을 약 4/3로 부풀리고, Comfy Router 호출은 전체 JSON 문서에 대해 10 MiB로 제한되므로, /v2/models/byteplus/\{model}로 전송되는 인라인 `audio_data`/`image_data` 참조는 디코딩 시 약 7.5 MB 미만이어야 합니다. 그보다 큰 경우에는 `audio_url`/`image_url`을 사용하세요. BytePlus 자체의 최대 10 MB 참조를 인라인하면 검증이 실행되기 전에 413으로 거부됩니다.
</ParamField>

<ParamField body="references[].audio_data" type="string">
  Base64로 인코딩된 참조 오디오입니다.
</ParamField>

<ParamField body="references[].audio_url" type="string">
  원격 참조 오디오 파일의 URL입니다.
</ParamField>

<ParamField body="references[].image_data" type="string">
  Base64로 인코딩된 참조 이미지입니다.
</ParamField>

<ParamField body="references[].image_url" type="string">
  원격 참조 이미지의 URL입니다.
</ParamField>

<ParamField body="references[].speaker" type="string">
  음성 ID입니다. 지원되는 Doubao TTS 음성 또는 복제된 음성 ID일 수 있습니다.
</ParamField>

<ParamField body="text_prompt" type="string" required>
  합성할 프롬프트 또는 텍스트입니다 (1\~3,000자, 빈 문자열은 거부됩니다). 오디오 참조를 제공한 경우 @Audio1, @Audio2, @Audio3을 사용하여 순서대로 참조하세요.
</ParamField>

<ParamField body="watermark" type="object">
  워터마크 구성 객체입니다. 빈 객체도 허용됩니다.
</ParamField>

<ParamField body="watermark.aigc_metadata" type="object">
  암시적 워터마크입니다. 합성된 오디오 헤더에 메타데이터를 추가합니다.
</ParamField>

<ParamField body="watermark.aigc_metadata.content_producer" type="string">
  합성 서비스 공급자의 이름 또는 코드입니다.
</ParamField>

<ParamField body="watermark.aigc_metadata.content_propagator" type="string">
  콘텐츠 배포 서비스 공급자의 이름 또는 코드입니다.
</ParamField>

<ParamField body="watermark.aigc_metadata.enable" type="boolean">
  암시적 워터마크를 사용할지 여부입니다 (기본값: false).
</ParamField>

<ParamField body="watermark.aigc_metadata.produce_id" type="string">
  콘텐츠 제작 ID입니다.
</ParamField>

<ParamField body="watermark.aigc_metadata.propagate_id" type="string">
  콘텐츠 배포 ID입니다.
</ParamField>

<ParamField body="watermark.aigc_watermark" type="boolean">
  명시적 워터마크 전환입니다. 합성된 오디오 끝에 오디오 리듬 마커를 추가합니다 (기본값: false).
</ParamField>

Router가 `GET /v2/models/byteplus/seed-audio-1.0-multilingual/openapi.json`에서 제공하는 스키마에서 생성되었으며, 이는 요청이 공급자에 도달하기 전에 호출 검증에 사용하는 것과 동일한 문서입니다.

### 출력

<ResponseField name="audio" type="string">
  생성된 오디오 데이터이며, Base64로 인코딩되어 있습니다.
</ResponseField>

<ResponseField name="code" type="integer">
  상태 코드입니다. 자세한 내용은 공식 오류 코드 문서를 참조하세요.
</ResponseField>

<ResponseField name="duration" type="number">
  속도 조정 또는 후처리 이후의 재생 시간(초)입니다.

  형식: `double`
</ResponseField>

<ResponseField name="message" type="string">
  상태 세부 정보입니다.
</ResponseField>

<ResponseField name="original_duration" type="number">
  원본 모델 출력 재생 시간(초)입니다. 과금에 사용되며 최대 120초로 제한됩니다.

  형식: `double`
</ResponseField>

<ResponseField name="subtitle" type="object">
  오디오의 자막 정보입니다. 요청에서 audio\_config.enable\_subtitle이 true로 설정된 경우에만 제공됩니다.
</ResponseField>

<ResponseField name="subtitle.sentences" type="object[]">
  발화 단위 자막 정보입니다.
</ResponseField>

<ResponseField name="subtitle.sentences[].end_time" type="integer">
  세그먼트 종료 시간이며, 오디오 시작점 기준 밀리초 단위입니다.
</ResponseField>

<ResponseField name="subtitle.sentences[].start_time" type="integer">
  세그먼트 시작 시간이며, 오디오 시작점 기준 밀리초 단위입니다.
</ResponseField>

<ResponseField name="subtitle.sentences[].text" type="string">
  세그먼트의 전체 텍스트입니다.
</ResponseField>

<ResponseField name="subtitle.text" type="string">
  오디오에 해당하는 자막 텍스트입니다.
</ResponseField>

<ResponseField name="subtitle.words" type="object[]">
  단어 단위 자막 정보입니다.
</ResponseField>

<ResponseField name="subtitle.words[].end_time" type="integer">
  세그먼트 종료 시간이며, 오디오 시작점 기준 밀리초 단위입니다.
</ResponseField>

<ResponseField name="subtitle.words[].start_time" type="integer">
  세그먼트 시작 시간이며, 오디오 시작점 기준 밀리초 단위입니다.
</ResponseField>

<ResponseField name="subtitle.words[].text" type="string">
  세그먼트의 전체 텍스트입니다.
</ResponseField>

<ResponseField name="url" type="string">
  임시 오디오 URL이며, 2시간 동안 유효합니다.
</ResponseField>

## 예시

### 입력

```json theme={null}
{
  "audio_config": {
    "format": "wav",
    "sample_rate": 24000
  },
  "text_prompt": "Hello from Comfy Router."
}
```

### 출력

```json theme={null}
{
  "audio": "PGJhc2U2ND4=",
  "duration": 1.2,
  "original_duration": 1.2,
  "url": "https://example.invalid/byteplus/seed-audio/generated.wav"
}
```

## 배포 전 확인

SDK는 `Idempotency-Key`를 생성하고 자동 재시도에서 재사용합니다. 수동 재시도 시에는 원래 키를 재사용하세요. Router는 연결을 최대 10분간 유지할 수 있습니다.

요청이 실패하면 Router는 이유를 설명하는 `X-Comfy-Error-Type` 응답 헤더를 보냅니다. `422`는 Router가 프로바이더를 호출하기 전에 입력을 거부했음을 의미합니다. 생성된 에셋은 [결과 URL이 만료](/ko/development/comfy-router/reference#결과-에셋)될 수 있으므로 즉시 다운로드하세요.

<CardGroup cols={3}>
  <Card title="헤더" icon="list" href="/ko/development/comfy-router/quickstart">
    인증, 멱등성, 요청 ID, 오류 분류, 재시도 간격, 지출 한도.
  </Card>

  <Card title="Router API 사용" icon="code" href="/ko/development/comfy-router/quickstart">
    모델 검색, 유효성 검사 오류, 재시도, 과금.
  </Card>

  <Card title="제한 사항" icon="triangle-exclamation" href="/ko/development/comfy-router/limitations">
    Router가 현재 지원하지 않는 기능과 대체 방법.
  </Card>
</CardGroup>