튜토리얼

개요

이 튜토리얼은 Tiro API를 사용해 오디오 파일을 업로드하고, 전사(transcription)를 받고, 여러 언어로 번역(translation)하는 전체 과정을 안내해요.

사전 준비물

엔터프라이즈 플랜 워크스페이스 — Voice File Job은 엔터프라이즈 플랜 전용이에요. 개요를 참고하세요.
유효한 Tiro API 키
작업을 만들 워크스페이스의 GUID. GET /v1/external/workspaces 응답의 guid를 TIRO_WORKSPACE_GUID 환경 변수에 넣어 두세요. 워크스페이스 API Key라면 그 키가 속한 워크스페이스의 GUID를 쓰세요.
오디오 파일 (MP3, WAV, M4A)
최대 파일 크기: 500MB
최대 길이: 4시간

1단계: Voice File Job(작업) 생성하기

원하는 전사·번역 설정으로 작업(job)을 생성하는 것부터 시작해요:

curl -X POST https://api.tiro.ooo/v1/external/voice-file/jobs \
  -H "Authorization: Bearer $TIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceGuid": "'"$TIRO_WORKSPACE_GUID"'",
    "transcriptLocaleHints": ["ko_KR"],
    "translationLocales": ["en_US"]
  }'

async function createVoiceFileJob() {
  const response = await fetch('https://api.tiro.ooo/v1/external/voice-file/jobs', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.TIRO_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspaceGuid: process.env.TIRO_WORKSPACE_GUID,
      transcriptLocaleHints: ['ko_KR'],
      translationLocales: ['en_US']
    })
  });
  
  if (!response.ok) {
    throw new Error(`Failed to create job: ${response.status}`);
  }
  
  const job = await response.json();
  console.log('Job created:', job.id);
  console.log('Upload URL:', job.uploadUri);
  
  return job;
}

import requests
import os

def create_voice_file_job():
    response = requests.post(
        'https://api.tiro.ooo/v1/external/voice-file/jobs',
        headers={
            'Authorization': f'Bearer {os.environ["TIRO_API_KEY"]}',
            'Content-Type': 'application/json'
        },
        json={
            'workspaceGuid': os.environ['TIRO_WORKSPACE_GUID'],
            'transcriptLocaleHints': ['ko_KR'],
            'translationLocales': ['en_US']
        }
    )
    
    response.raise_for_status()
    job = response.json()
    
    print(f'Job created: {job["id"]}')
    print(f'Upload URL: {job["uploadUri"]}')
    
    return job

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

type CreateJobRequest struct {
    WorkspaceGuid         string   `json:"workspaceGuid"`
    TranscriptLocaleHints []string `json:"transcriptLocaleHints"`
    TranslationLocales    []string `json:"translationLocales"`
}

type CreateJobResponse struct {
    ID        string `json:"id"`
    UploadUri string `json:"uploadUri"`
}

func createVoiceFileJob() (*CreateJobResponse, error) {
    reqBody := CreateJobRequest{
        WorkspaceGuid:         os.Getenv("TIRO_WORKSPACE_GUID"),
        TranscriptLocaleHints: []string{"ko_KR"},
        TranslationLocales:    []string{"en_US"},
    }
    
    jsonBody, _ := json.Marshal(reqBody)
    
    req, _ := http.NewRequest("POST", "https://api.tiro.ooo/v1/external/voice-file/jobs", bytes.NewBuffer(jsonBody))
    req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("TIRO_API_KEY")))
    req.Header.Set("Content-Type", "application/json")
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    var job CreateJobResponse
    json.NewDecoder(resp.Body).Decode(&job)
    
    fmt.Printf("Job created: %s\n", job.ID)
    fmt.Printf("Upload URL: %s\n", job.UploadUri)
    
    return &job, nil
}

import org.springframework.beans.factory.annotation.Value
import org.springframework.http.*
import org.springframework.web.client.RestTemplate

data class CreateJobRequest(
    val workspaceGuid: String,
    val transcriptLocaleHints: List<String>,
    val translationLocales: List<String>
)

data class CreateJobResponse(
    val id: String,
    val uploadUri: String
)

@Service
class VoiceFileService {
    
    @Value("\${tiro.api.key}")
    private lateinit var apiKey: String

    @Value("\${tiro.workspace.guid}")
    private lateinit var workspaceGuid: String
    
    private val restTemplate = RestTemplate()
    
    fun createVoiceFileJob(): CreateJobResponse {
        val headers = HttpHeaders().apply {
            set("Authorization", "Bearer $apiKey")
            contentType = MediaType.APPLICATION_JSON
        }
        
        val request = CreateJobRequest(
            workspaceGuid = workspaceGuid,
            transcriptLocaleHints = listOf("ko_KR"),
            translationLocales = listOf("en_US")
        )
        
        val entity = HttpEntity(request, headers)
        
        val response = restTemplate.exchange(
            "https://api.tiro.ooo/v1/external/voice-file/jobs",
            HttpMethod.POST,
            entity,
            CreateJobResponse::class.java
        )
        
        val job = response.body!!
        println("Job created: ${job.id}")
        println("Upload URL: ${job.uploadUri}")
        
        return job
    }
}

응답 예시:

{
  "id": "b2d1ab32-3fe2-4201-b0b4-391abdbaa023",
  "uploadUri": "https://storage.example.com/upload/signed-url"
}

2단계: 오디오 파일 업로드하기

제공된 서명 URL(signed URL)에 오디오 파일을 업로드해요:

# Upload audio file to the signed URL (replace UPLOAD_URI with the uploadUri from Step 1)
curl -X PUT "$UPLOAD_URI" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @/path/to/your/audio.mp3

async function uploadAudioFile(uploadUri, audioFile) {
  const response = await fetch(uploadUri, {
    method: 'PUT',
    body: audioFile,
    headers: {
      'Content-Type': audioFile.type || 'audio/mpeg'
    }
  });
  
  if (!response.ok) {
    throw new Error(`Upload failed: ${response.status}`);
  }
  
  console.log('File uploaded successfully');
}

// For Node.js with file system
const fs = require('fs');

async function uploadAudioFileNode(uploadUri, filePath) {
  const fileBuffer = fs.readFileSync(filePath);
  
  const response = await fetch(uploadUri, {
    method: 'PUT',
    body: fileBuffer,
    headers: {
      'Content-Type': 'audio/mpeg'
    }
  });
  
  if (!response.ok) {
    throw new Error(`Upload failed: ${response.status}`);
  }
  
  console.log('File uploaded successfully');
}

def upload_audio_file(upload_uri, file_path):
    with open(file_path, 'rb') as audio_file:
        response = requests.put(
            upload_uri,
            data=audio_file,
            headers={'Content-Type': 'audio/mpeg'}
        )
    
    response.raise_for_status()
    print('File uploaded successfully')

func uploadAudioFile(uploadUri, filePath string) error {
    file, err := os.Open(filePath)
    if err != nil {
        return err
    }
    defer file.Close()
    
    req, _ := http.NewRequest("PUT", uploadUri, file)
    req.Header.Set("Content-Type", "audio/mpeg")
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    
    if resp.StatusCode != http.StatusOK {
        return fmt.Errorf("upload failed: %d", resp.StatusCode)
    }
    
    fmt.Println("File uploaded successfully")
    return nil
}

fun uploadAudioFile(uploadUri: String, filePath: String) {
    val file = File(filePath)
    val headers = HttpHeaders().apply {
        contentType = MediaType.parseMediaType("audio/mpeg")
    }
    
    val resource = FileSystemResource(file)
    val entity = HttpEntity(resource, headers)
    
    val response = restTemplate.exchange(
        uploadUri,
        HttpMethod.PUT,
        entity,
        String::class.java
    )
    
    if (response.statusCode.is2xxSuccessful) {
        println("File uploaded successfully")
    } else {
        throw RuntimeException("Upload failed: ${response.statusCode}")
    }
}

3단계: 업로드 완료 알리기

업로드가 완료되었음을 API에 알려요:

curl -X PUT "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID/upload-complete" \
  -H "Authorization: Bearer $TIRO_API_KEY" \
  -H "Content-Type: application/json"

async function notifyUploadComplete(jobId) {
  const response = await fetch(
    `https://api.tiro.ooo/v1/external/voice-file/jobs/${jobId}/upload-complete`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${process.env.TIRO_API_KEY}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  if (!response.ok) {
    throw new Error(`Failed to notify upload: ${response.status}`);
  }
  
  console.log('Upload notification sent');
}

def notify_upload_complete(job_id):
    response = requests.put(
        f'https://api.tiro.ooo/v1/external/voice-file/jobs/{job_id}/upload-complete',
        headers={
            'Authorization': f'Bearer {os.getenv("TIRO_API_KEY")}',
            'Content-Type': 'application/json'
        }
    )
    
    response.raise_for_status()
    print('Upload notification sent')

func notifyUploadComplete(jobId string) error {
    url := fmt.Sprintf("https://api.tiro.ooo/v1/external/voice-file/jobs/%s/upload-complete", jobId)
    
    req, _ := http.NewRequest("PUT", url, nil)
    req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("TIRO_API_KEY")))
    req.Header.Set("Content-Type", "application/json")
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    
    fmt.Println("Upload notification sent")
    return nil
}

fun notifyUploadComplete(jobId: String) {
    val headers = HttpHeaders().apply {
        set("Authorization", "Bearer $apiKey")
        contentType = MediaType.APPLICATION_JSON
    }
    
    val entity = HttpEntity<String>(headers)
    
    restTemplate.exchange(
        "https://api.tiro.ooo/v1/external/voice-file/jobs/$jobId/upload-complete",
        HttpMethod.PUT,
        entity,
        String::class.java
    )
    
    println("Upload notification sent")
}

4단계: 작업 완료 폴링하기

처리가 완료될 때까지 작업 상태를 모니터링해요:

이 튜토리얼은 스크립트 하나로 끝까지 실행할 수 있게 폴링을 써요. 운영 환경에서는 voice_file_job.completed와 voice_file_job.failed 웹훅으로 완료를 받으세요. 구독 방법은 Voice File 개요에 있어요.

# Check job status (poll until status is COMPLETED or FAILED)
curl -X GET "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID" \
  -H "Authorization: Bearer $TIRO_API_KEY"

# Example response:
# {
#   "id": "b2d1ab32-3fe2-4201-b0b4-391abdbaa023",
#   "status": "COMPLETED",
#   "fileUploadedAt": "2024-01-01T12:00:20Z",
#   "processStartedAt": "2024-01-01T12:01:00Z",
#   "processCompletedAt": "2024-01-01T12:02:30Z"
# }

async function waitForJobCompletion(jobId) {
  let delay = 2000; // Start with 2 seconds
  const maxDelay = 30000; // Max 30 seconds
  const maxAttempts = 60; // 30 minutes max
  let attempts = 0;
  
  while (attempts < maxAttempts) {
    try {
      const response = await fetch(
        `https://api.tiro.ooo/v1/external/voice-file/jobs/${jobId}`,
        {
          headers: {
            'Authorization': `Bearer ${process.env.TIRO_API_KEY}`
          }
        }
      );
      
      if (!response.ok) {
        throw new Error(`Failed to get job status: ${response.status}`);
      }
      
      const job = await response.json();
      console.log(`Job status: ${job.status}`);
      
      if (job.status === 'COMPLETED') {
        console.log('Job completed successfully!');
        return job;
      }
      
      if (job.status === 'FAILED') {
        throw new Error(`Job failed: ${job.errorMessage || 'Unknown error'}`);
      }
      
      // Still processing - wait with exponential backoff
      await new Promise(resolve => setTimeout(resolve, delay));
      delay = Math.min(delay * 1.2, maxDelay);
      attempts++;
      
    } catch (error) {
      console.error('Error checking job status:', error);
      attempts++;
      await new Promise(resolve => setTimeout(resolve, delay));
      delay = Math.min(delay * 1.5, maxDelay);
    }
  }
  
  throw new Error('Job did not complete within timeout');
}

import time
import asyncio

async def wait_for_job_completion(job_id):
    delay = 2  # Start with 2 seconds
    max_delay = 30  # Max 30 seconds
    max_attempts = 60  # 30 minutes max
    attempts = 0
    
    while attempts < max_attempts:
        try:
            response = requests.get(
                f'https://api.tiro.ooo/v1/external/voice-file/jobs/{job_id}',
                headers={
                    'Authorization': f'Bearer {os.getenv("TIRO_API_KEY")}'
                }
            )
            
            response.raise_for_status()
            job = response.json()
            print(f'Job status: {job["status"]}')
            
            if job['status'] == 'COMPLETED':
                print('Job completed successfully!')
                return job
                
            if job['status'] == 'FAILED':
                error_msg = job.get('errorMessage', 'Unknown error')
                raise Exception(f'Job failed: {error_msg}')
                
            # Still processing - wait with exponential backoff
            await asyncio.sleep(delay)
            delay = min(delay * 1.2, max_delay)
            attempts += 1
            
        except Exception as e:
            print(f'Error checking job status: {e}')
            attempts += 1
            await asyncio.sleep(delay)
            delay = min(delay * 1.5, max_delay)
    
    raise Exception('Job did not complete within timeout')

type JobStatus struct {
    ID        string `json:"id"`
    Status    string `json:"status"`
    ErrorMessage string `json:"errorMessage,omitempty"`
}

func waitForJobCompletion(jobId string) (*JobStatus, error) {
    delay := 2 * time.Second
    maxDelay := 30 * time.Second
    maxAttempts := 60
    
    client := &http.Client{}
    url := fmt.Sprintf("https://api.tiro.ooo/v1/external/voice-file/jobs/%s", jobId)
    
    for attempts := 0; attempts < maxAttempts; attempts++ {
        req, _ := http.NewRequest("GET", url, nil)
        req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("TIRO_API_KEY")))
        
        resp, err := client.Do(req)
        if err != nil {
            time.Sleep(delay)
            delay = time.Duration(float64(delay) * 1.5)
            if delay > maxDelay {
                delay = maxDelay
            }
            continue
        }
        
        var job JobStatus
        json.NewDecoder(resp.Body).Decode(&job)
        resp.Body.Close()
        
        fmt.Printf("Job status: %s\n", job.Status)
        
        if job.Status == "COMPLETED" {
            fmt.Println("Job completed successfully!")
            return &job, nil
        }
        
        if job.Status == "FAILED" {
            return nil, fmt.Errorf("job failed: %s", job.ErrorMessage)
        }
        
        time.Sleep(delay)
        delay = time.Duration(float64(delay) * 1.2)
        if delay > maxDelay {
            delay = maxDelay
        }
    }
    
    return nil, fmt.Errorf("job did not complete within timeout")
}

import java.util.concurrent.TimeUnit

data class JobStatus(
    val id: String,
    val status: String,
    val errorMessage: String? = null
)

fun waitForJobCompletion(jobId: String): JobStatus {
    var delay = 2000L // 2 seconds
    val maxDelay = 30000L // 30 seconds
    val maxAttempts = 60
    
    repeat(maxAttempts) { attempt ->
        try {
            val headers = HttpHeaders().apply {
                set("Authorization", "Bearer $apiKey")
            }
            
            val entity = HttpEntity<String>(headers)
            
            val response = restTemplate.exchange(
                "https://api.tiro.ooo/v1/external/voice-file/jobs/$jobId",
                HttpMethod.GET,
                entity,
                JobStatus::class.java
            )
            
            val job = response.body!!
            println("Job status: ${job.status}")
            
            when (job.status) {
                "COMPLETED" -> {
                    println("Job completed successfully!")
                    return job
                }
                "FAILED" -> {
                    throw RuntimeException("Job failed: ${job.errorMessage}")
                }
            }
            
            TimeUnit.MILLISECONDS.sleep(delay)
            delay = minOf((delay * 1.2).toLong(), maxDelay)
            
        } catch (e: Exception) {
            println("Error checking job status: ${e.message}")
            TimeUnit.MILLISECONDS.sleep(delay)
            delay = minOf((delay * 1.5).toLong(), maxDelay)
        }
    }
    
    throw RuntimeException("Job did not complete within timeout")
}

5단계: 결과 조회하기

작업이 완료되면 전사 결과와 번역 결과를 가져와요:

# Get transcript
curl -X GET "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID/transcript" \
  -H "Authorization: Bearer $TIRO_API_KEY"

# Get all translations
curl -X GET "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID/translations" \
  -H "Authorization: Bearer $TIRO_API_KEY"

# Get specific translation (e.g., English)
curl -X GET "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID/translations/en_US" \
  -H "Authorization: Bearer $TIRO_API_KEY"

# Get transcript paragraph summary
curl -X GET "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID/transcript/paragraph-summary" \
  -H "Authorization: Bearer $TIRO_API_KEY"

# Get translation paragraph summary
curl -X GET "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID/translations/en_US/paragraph-summary" \
  -H "Authorization: Bearer $TIRO_API_KEY"

async function getJobResults(jobId) {
  // Get transcript
  const transcriptResponse = await fetch(
    `https://api.tiro.ooo/v1/external/voice-file/jobs/${jobId}/transcript`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.TIRO_API_KEY}`
      }
    }
  );
  
  if (!transcriptResponse.ok) {
    throw new Error(`Failed to get transcript: ${transcriptResponse.status}`);
  }
  
  const transcript = await transcriptResponse.json();
  console.log('Transcript:', transcript.text);
  
  // Get available translations
  const translationsResponse = await fetch(
    `https://api.tiro.ooo/v1/external/voice-file/jobs/${jobId}/translations`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.TIRO_API_KEY}`
      }
    }
  );
  
  if (!translationsResponse.ok) {
    throw new Error(`Failed to get translations: ${translationsResponse.status}`);
  }
  
  const translations = await translationsResponse.json();
  
  // Get each translation
  const translationResults = {};
  for (const translation of translations) {
    translationResults[translation.locale] = translation.text;
  }
  
  // Get paragraph summaries
  const transcriptSummaryResponse = await fetch(
    `https://api.tiro.ooo/v1/external/voice-file/jobs/${jobId}/transcript/paragraph-summary`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.TIRO_API_KEY}`
      }
    }
  );
  
  let transcriptSummary = null;
  if (transcriptSummaryResponse.ok) {
    transcriptSummary = await transcriptSummaryResponse.json();
  }

  // Get translation summaries
  const translationSummaries = {};
  for (const translation of translations) {
    const summaryResponse = await fetch(
      `https://api.tiro.ooo/v1/external/voice-file/jobs/${jobId}/translations/${translation.locale}/paragraph-summary`,
      {
        headers: {
          'Authorization': `Bearer ${process.env.TIRO_API_KEY}`
        }
      }
    );
    
    if (summaryResponse.ok) {
      const summaryData = await summaryResponse.json();
      translationSummaries[translation.locale] = summaryData.summary;
    }
  }

  return {
    transcript: transcript.text,
    translations: translationResults,
    transcriptSummary: transcriptSummary?.summary,
    translationSummaries
  };
}

def get_job_results(job_id):
    # Get transcript
    transcript_response = requests.get(
        f'https://api.tiro.ooo/v1/external/voice-file/jobs/{job_id}/transcript',
        headers={'Authorization': f'Bearer {os.getenv("TIRO_API_KEY")}'}
    )
    transcript_response.raise_for_status()
    transcript = transcript_response.json()
    
    print(f'Transcript: {transcript["text"]}')
    
    # Get available translations
    translations_response = requests.get(
        f'https://api.tiro.ooo/v1/external/voice-file/jobs/{job_id}/translations',
        headers={'Authorization': f'Bearer {os.getenv("TIRO_API_KEY")}'}
    )
    translations_response.raise_for_status()
    translations = translations_response.json()
    
    # Get each translation
    translation_results = {}
    for translation in translations:
        translation_results[translation['locale']] = translation['text']
    
    # Get paragraph summaries
    transcript_summary = None
    try:
        transcript_summary_response = requests.get(
            f'https://api.tiro.ooo/v1/external/voice-file/jobs/{job_id}/transcript/paragraph-summary',
            headers={'Authorization': f'Bearer {os.getenv("TIRO_API_KEY")}'}
        )
        if transcript_summary_response.ok:
            transcript_summary_data = transcript_summary_response.json()
            transcript_summary = transcript_summary_data['summary']
    except:
        pass

    # Get translation summaries
    translation_summaries = {}
    for translation in translations:
        try:
            summary_response = requests.get(
                f'https://api.tiro.ooo/v1/external/voice-file/jobs/{job_id}/translations/{translation["locale"]}/paragraph-summary',
                headers={'Authorization': f'Bearer {os.getenv("TIRO_API_KEY")}'}
            )
            
            if summary_response.ok:
                summary_data = summary_response.json()
                translation_summaries[translation['locale']] = summary_data['summary']
        except:
            pass
    
    return {
        'transcript': transcript['text'],
        'translations': translation_results,
        'transcript_summary': transcript_summary,
        'translation_summaries': translation_summaries
    }

type Transcript struct {
    JobId   string   `json:"jobId"`
    Locales []string `json:"locales"`
    Text    string   `json:"text"`
}

type Translation struct {
    JobId  string `json:"jobId"`
    Locale string `json:"locale"`
    Text   string `json:"text"`
}

type JobResults struct {
    Transcript   string
    Translations map[string]string
}

func getJobResults(jobId string) (*JobResults, error) {
    client := &http.Client{}
    apiKey := os.Getenv("TIRO_API_KEY")
    
    // Get transcript
    transcriptUrl := fmt.Sprintf("https://api.tiro.ooo/v1/external/voice-file/jobs/%s/transcript", jobId)
    req, _ := http.NewRequest("GET", transcriptUrl, nil)
    req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", apiKey))
    
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    var transcript Transcript
    json.NewDecoder(resp.Body).Decode(&transcript)
    fmt.Printf("Transcript: %s\n", transcript.Text)
    
    // Get translations
    translationsUrl := fmt.Sprintf("https://api.tiro.ooo/v1/external/voice-file/jobs/%s/translations", jobId)
    req, _ = http.NewRequest("GET", translationsUrl, nil)
    req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", apiKey))
    
    resp, err = client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    var translations []Translation
    json.NewDecoder(resp.Body).Decode(&translations)
    
    translationResults := make(map[string]string)
    for _, t := range translations {
        translationResults[t.Locale] = t.Text
    }
    
    return &JobResults{
        Transcript:   transcript.Text,
        Translations: translationResults,
    }, nil
}

data class Transcript(
    val jobId: String,
    val locales: List<String>,
    val text: String
)

data class Translation(
    val jobId: String,
    val locale: String,
    val text: String
)

data class JobResults(
    val transcript: String,
    val translations: Map<String, String>
)

fun getJobResults(jobId: String): JobResults {
    val headers = HttpHeaders().apply {
        set("Authorization", "Bearer $apiKey")
    }
    val entity = HttpEntity<String>(headers)
    
    // Get transcript
    val transcriptResponse = restTemplate.exchange(
        "https://api.tiro.ooo/v1/external/voice-file/jobs/$jobId/transcript",
        HttpMethod.GET,
        entity,
        Transcript::class.java
    )
    val transcript = transcriptResponse.body!!
    println("Transcript: ${transcript.text}")
    
    // Get translations
    val translationsResponse = restTemplate.exchange(
        "https://api.tiro.ooo/v1/external/voice-file/jobs/$jobId/translations",
        HttpMethod.GET,
        entity,
        object : ParameterizedTypeReference<List<Translation>>() {}
    )
    val translations = translationsResponse.body!!
    
    val translationResults = translations.associate { it.locale to it.text }
    
    return JobResults(
        transcript = transcript.text,
        translations = translationResults
    )
}

전체 예제

다음은 오디오 파일을 처음부터 끝까지 처리하는 전체 예제예요:

#!/bin/bash
# Complete Voice File Processing Script

# Set your API key
export TIRO_API_KEY="your_api_key_here"
export TIRO_WORKSPACE_GUID="your_workspace_guid_here"
AUDIO_FILE="/path/to/your/audio.mp3"

# Step 1: Create job
echo "Creating voice file job..."
RESPONSE=$(curl -s -X POST https://api.tiro.ooo/v1/external/voice-file/jobs \
  -H "Authorization: Bearer $TIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceGuid": "'"$TIRO_WORKSPACE_GUID"'",
    "transcriptLocaleHints": ["ko_KR"],
    "translationLocales": ["en_US"]
  }')

JOB_ID=$(echo $RESPONSE | jq -r '.id')
UPLOAD_URI=$(echo $RESPONSE | jq -r '.uploadUri')
echo "Job created: $JOB_ID"

# Step 2: Upload file
echo "Uploading audio file..."
curl -s -X PUT "$UPLOAD_URI" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @"$AUDIO_FILE"
echo "File uploaded successfully"

# Step 3: Notify upload complete
echo "Notifying upload completion..."
curl -s -X PUT "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID/upload-complete" \
  -H "Authorization: Bearer $TIRO_API_KEY" \
  -H "Content-Type: application/json"

# Step 4: Poll for completion
echo "Waiting for processing to complete..."
while true; do
  STATUS=$(curl -s -X GET "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID" \
    -H "Authorization: Bearer $TIRO_API_KEY" | jq -r '.status')
  echo "Status: $STATUS"
  
  if [ "$STATUS" = "COMPLETED" ]; then
    echo "Job completed successfully!"
    break
  elif [ "$STATUS" = "FAILED" ]; then
    echo "Job failed!"
    exit 1
  fi
  
  sleep 5
done

# Step 5: Get results
echo "Retrieving results..."

echo "=== Transcript ==="
curl -s -X GET "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID/transcript" \
  -H "Authorization: Bearer $TIRO_API_KEY" | jq '.text'

echo "=== Translation (en_US) ==="
curl -s -X GET "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID/translations/en_US" \
  -H "Authorization: Bearer $TIRO_API_KEY" | jq '.text'

echo "=== Paragraph Summary ==="
curl -s -X GET "https://api.tiro.ooo/v1/external/voice-file/jobs/$JOB_ID/transcript/paragraph-summary" \
  -H "Authorization: Bearer $TIRO_API_KEY" | jq '.summary'

echo "Processing completed!"

async function processAudioFile(audioFile) {
  try {
    // Step 1: Create job
    console.log('Creating voice file job...');
    const job = await createVoiceFileJob();
    
    // Step 2: Upload file
    console.log('Uploading audio file...');
    await uploadAudioFile(job.uploadUri, audioFile);
    
    // Step 3: Notify upload complete
    console.log('Notifying upload completion...');
    await notifyUploadComplete(job.id);
    
    // Step 4: Wait for processing
    console.log('Waiting for processing to complete...');
    const completedJob = await waitForJobCompletion(job.id);
    
    // Step 5: Get results
    console.log('Retrieving results...');
    const results = await getJobResults(job.id);
    
    console.log('Processing completed!');
    console.log('Transcript:', results.transcript);
    console.log('Translations:', results.translations);
    console.log('Transcript Summary:', results.transcriptSummary);
    console.log('Translation Summaries:', results.translationSummaries);
    
    return results;
    
  } catch (error) {
    console.error('Error processing audio file:', error);
    throw error;
  }
}

// Usage
processAudioFile(myAudioFile)
  .then(results => {
    // Handle successful processing
    displayResults(results);
  })
  .catch(error => {
    // Handle error
    showError(error.message);
  });

async def process_audio_file(file_path):
    try:
        # Step 1: Create job
        print('Creating voice file job...')
        job = create_voice_file_job()
        
        # Step 2: Upload file
        print('Uploading audio file...')
        upload_audio_file(job['uploadUri'], file_path)
        
        # Step 3: Notify upload complete
        print('Notifying upload completion...')
        notify_upload_complete(job['id'])
        
        # Step 4: Wait for processing
        print('Waiting for processing to complete...')
        completed_job = await wait_for_job_completion(job['id'])
        
        # Step 5: Get results
        print('Retrieving results...')
        results = get_job_results(job['id'])
        
        print('Processing completed!')
        print(f'Transcript: {results["transcript"]}')
        print(f'Translations: {results["translations"]}')
        print(f'Transcript Summary: {results["transcript_summary"]}')
        print(f'Translation Summaries: {results["translation_summaries"]}')
        
        return results
        
    except Exception as e:
        print(f'Error processing audio file: {e}')
        raise

# Usage
if __name__ == '__main__':
    asyncio.run(process_audio_file('path/to/audio.mp3'))

6단계: 문단 요약(paragraph summary) 이해하기

문단 요약(Paragraph Summary) 기능은 지능형 콘텐츠 요약을 제공해, 오디오 파일의 핵심 내용을 빠르게 파악할 수 있도록 도와줘요.

문단 요약이란 무엇인가요?

문단 요약은 전사 또는 번역 콘텐츠를 논리적인 섹션으로 나눠 자동으로 생성한 개요예요. 각 요약은 다음을 제공해요:

간결한 개요: 각 문단의 핵심 내용을 마크다운 형식으로 제공
언어별 제공: 전사와 번역 모두에 대해 요약 생성
구조화된 콘텐츠: 파싱하기 쉽고 애플리케이션에 통합하기 쉬움

응답 예시

문단 요약을 가져오면 다음과 같은 응답을 받게 돼요. summary는 type이 text/markdown인 객체 하나이고, 모든 문단의 요약이 content에 마크다운으로 이어져 있어요.

{
  "jobId": "b2d1ab32-3fe2-4201-b0b4-391abdbaa023",
  "locale": "ko_KR",
  "summary": {
    "type": "text/markdown",
    "content": "### 프로젝트 진행 상황 점검\n\n* 각 팀원이 담당 업무의 현재 상태를 보고했습니다.\n* 일정에 영향을 주는 이슈를 논의했습니다.\n\n### 다음 단계 계획\n\n* 다음 스프린트 목표를 정했습니다."
  }
}

요약은 언제 이용할 수 있나요?

전사 및 번역 요약: 작업 완료 후(COMPLETED 상태) 이용할 수 있어요
- COMPLETED는 모든 처리가 끝났음을 의미해요: 전사, 번역(요청한 경우), 그리고 둘 모두에 대한 문단 요약
완료 전에 조회하면: 요약이 아직 준비되지 않았으면 문단 요약 endpoint가 422013 오류를 반환해요. voice_file_job.completed 이벤트나 COMPLETED 상태를 확인한 뒤 조회하세요

폴링 모범 사례

지수 백오프(exponential backoff) 전략

시작 지연: 2초 (처리가 시작되는 데 시간이 걸려요)
증가 계수: 1.2배 (완만한 증가)
최대 지연: 30초 (서버에 과부하를 주지 않도록)
최대 시도 횟수: 예상 처리 시간에 기반해서 결정

작업 상태 전이

처리 시간 가이드라인

파일 길이	예상 처리 시간	권장 폴링 간격
< 5분	45~75초	시작: 2s, 최대: 10s
5~20분	1~3분	시작: 5s, 최대: 20s
20~60분	3~6분	시작: 10s, 최대: 30s
1~4시간	6~18분	시작: 30s, 최대: 60s

자주 발생하는 문제와 해결 방법

업로드 실패

문제: 413 Payload Too Large
해결: 파일 크기(최대 500MB)를 확인하고 필요하면 압축하세요

처리 실패

문제: 낮은 오디오 품질
해결: 샘플 레이트가 ≥8kHz이고 배경 소음이 최소화되었는지 확인하세요

타임아웃 문제

문제: 작업이 예상 시간 내에 완료되지 않음
해결: 더 긴 파일에는 타임아웃을 늘리고, 오류가 있는지 작업 상태를 확인하세요

더 큰 그림을 다시 살펴보려면 Voice File 개요를 참고하고, 모든 파라미터와 응답 필드는 API 레퍼런스에서 확인하세요.

홈

시작하기

API

음성 파일

웹훅

MCP

CLI

개발자 리소스

개요

사전 준비물

1단계: Voice File Job(작업) 생성하기

2단계: 오디오 파일 업로드하기

3단계: 업로드 완료 알리기

4단계: 작업 완료 폴링하기

5단계: 결과 조회하기

전체 예제

6단계: 문단 요약(paragraph summary) 이해하기

문단 요약이란 무엇인가요?

응답 예시

요약은 언제 이용할 수 있나요?

폴링 모범 사례

지수 백오프(exponential backoff) 전략

작업 상태 전이

처리 시간 가이드라인

자주 발생하는 문제와 해결 방법

업로드 실패

처리 실패

타임아웃 문제

​개요

​사전 준비물

​1단계: Voice File Job(작업) 생성하기

​2단계: 오디오 파일 업로드하기

​3단계: 업로드 완료 알리기

​4단계: 작업 완료 폴링하기

​5단계: 결과 조회하기

​전체 예제

​6단계: 문단 요약(paragraph summary) 이해하기

​문단 요약이란 무엇인가요?

​응답 예시

​요약은 언제 이용할 수 있나요?

​폴링 모범 사례

​지수 백오프(exponential backoff) 전략

​작업 상태 전이

​처리 시간 가이드라인

​자주 발생하는 문제와 해결 방법

​업로드 실패

​처리 실패

​타임아웃 문제

개요

사전 준비물

1단계: Voice File Job(작업) 생성하기

2단계: 오디오 파일 업로드하기

3단계: 업로드 완료 알리기

4단계: 작업 완료 폴링하기

5단계: 결과 조회하기

전체 예제

6단계: 문단 요약(paragraph summary) 이해하기

문단 요약이란 무엇인가요?

응답 예시

요약은 언제 이용할 수 있나요?

폴링 모범 사례

지수 백오프(exponential backoff) 전략

작업 상태 전이

처리 시간 가이드라인

자주 발생하는 문제와 해결 방법

업로드 실패

처리 실패

타임아웃 문제