API 예제

버전

API

경로

POST PUT POST

/api/v2/api/translate/uploads
R2 target
/api/v2/api/translate

매개변수

매개변수	필수	유형	설명
`image`	예	file[]	하나 이상의 이미지 파일 또는 하나의 ZIP 압축 파일
`source_language`	아니요	string	선택 사항이며 manga 모델을 선택하면 필수입니다(예: ja)
`target_language`	예	string	대상 언어 코드(예: en)
`model`	아니요	string	인식 모델. 생략하면 API 기본값을 사용합니다
`font`	아니요	string	글꼴 스타일. 생략하면 API 기본값을 사용합니다

매개변수	필수	유형	설명
`Idempotency-Key`	예	HTTP header	준비 요청 헤더: 8시간 동안 동일한 파일 목록을 안전하게 재시도하기 위한 고정 키
`platform`	아니요	string \| null	준비 및 최종 요청: API 호출 감사에만 사용하는 선택적 자체 보고 플랫폼 레이블
`files[]`	예	array<object>	준비 요청: filename, content_type, size, content_sha256을 포함한 파일 메타데이터
`upload_id`	예	string	최종 요청: 준비 단계에서 반환된 불투명 업로드 배치 ID
`files[].index files[].upload_intent`	예	integer string	최종 요청: 준비 단계에서 반환된 파일별 index와 불투명 upload_intent. 각 R2 업로드가 끝난 뒤에 전송합니다
`source_language`	아니요	string	선택 사항이며 manga 모델을 선택하면 필수입니다(예: ja)
`target_language`	예	string	대상 언어 코드(예: en)
`model`	아니요	string	인식 모델. 생략하면 API 기본값을 사용합니다
`font`	아니요	string	글꼴 스타일. 생략하면 API 기본값을 사용합니다

매개변수	필수	유형	설명
`batch_id`	예	string	작업 상태 조회에 사용하는 배치 식별자

매개변수	필수	유형	설명
매개변수 없음

응답 매개변수

필드	유형	설명
`task_id`	string	작업 식별자
`batch_id`	string	작업 상태 조회에 사용하는 배치 식별자

필드	유형	설명
`status`	integer	애플리케이션 상태 코드이며 성공 시 200
`cost_ms`	integer	이 API 요청을 처리하는 데 걸린 시간(밀리초)
`request_id`	string	이 API 호출을 추적하기 위한 요청 식별자
`data`	object	요청 수락 후 반환되는 번역 작업 식별자
`message`	string	성공한 API 응답에서는 항상 success이며 번역 작업 완료를 의미하지 않습니다
`data.task_id`	string	작업 식별자
`data.batch_id`	string	작업 상태 조회에 사용하는 배치 식별자

필드	유형	설명
`status_code`	integer	Task Status 성공 응답에서는 항상 200
`request_id`	string	이 API 호출을 추적하기 위한 요청 식별자
`auth_type`	string	PAT 인증 Task Status 요청에서는 항상 account
`task_reference`	string	요청 경로의 batch_id를 변경 없이 반환
`data`	object	이미지별 결과와 전체 작업 상태를 담는 객체
`data.items`	array<object>	이미지별 작업 결과 배열
`data.items[].image_id`	string	이미지 결과의 안정적인 식별자
`data.items[].index`	integer	배치에서 이미지의 0부터 시작하는 위치
`data.items[].filename`	string	원본 이미지 파일 이름
`data.items[].status`	string	이미지 결과 상태(pending \| processing \| completed \| failed \| canceled)
`data.items[].original_url`	string	원본 이미지 URL입니다. 현재 API로 생성한 작업에서 제공됩니다.
`data.items[].translated_url`	string	번역 이미지 URL입니다. 번역 결과를 사용할 수 있기 전에는 빈 문자열이며 대기, 처리 중 또는 실패 이미지도 포함됩니다.
`data.items[].is_translated`	boolean	완료된 번역 이미지 URL을 사용할 수 있을 때만 true
`data.items[].output_file_path`	string	translated_url의 호환 별칭입니다. 번역 이미지가 없으면 빈 문자열입니다.
`data.items[].message`	string \| null	선택적 정보 메시지
`data.items[].error`	string \| null	이미지 작업 실패 시 오류 상세이며 그 외에는 null
`data.items[].inpaint_image_url`	string \| null	문자 제거 이미지 URL이며 선택한 모델 또는 실행 경로가 생성하지 않으면 null입니다.
`data.items[].block_json`	array<object>	V1에 유지되는 구조화 텍스트 블록입니다. 선택한 모델 또는 실행 경로가 블록 메타데이터를 반환하지 않으면 빈 배열일 수 있습니다.
`data.task_status`	string	전체 작업 상태(pending \| processing \| completed \| failed \| canceled)

필드	유형	설명
`status`	integer	애플리케이션 상태 코드이며 성공 시 200
`cost_ms`	integer	작업 경과 시간(밀리초)이며 유효한 작업 타임스탬프가 없으면 0
`request_id`	string	이 API 호출을 추적하기 위한 요청 식별자
`data`	array<object>	간결한 이미지별 결과 배열
`message`	string	성공한 API 응답에서는 항상 success이며 번역 작업 완료를 의미하지 않습니다
`data[].image_id`	string	이미지 결과의 안정적인 식별자
`data[].filename`	string	원본 이미지 파일 이름
`data[].status`	string	이미지 결과 상태(pending \| processing \| completed \| failed \| canceled)
`data[].original_url`	string	원본 이미지 URL입니다. 현재 API로 생성한 작업에서 제공됩니다.
`data[].translated_url`	string	번역 이미지 URL입니다. 번역 결과를 사용할 수 있기 전에는 빈 문자열이며 대기, 처리 중 또는 실패 이미지도 포함됩니다.
`data[].erased_url`	string	문자 제거 이미지 URL이며 빈 문자열일 수 있습니다. Manga + Auto 완성 이미지 경로처럼 완성 이미지만 반환하는 모델 또는 실행 경로에서는 생성되지 않습니다.
`data[].blocks`	array<object>	구조화된 번역 텍스트 블록입니다. Manga + Auto 완성 이미지 경로처럼 선택한 모델 또는 실행 경로가 블록 메타데이터를 반환하지 않으면 빈 배열일 수 있습니다.
`data[].blocks[].angle`	number	텍스트 블록의 회전 각도
`data[].blocks[].color`	string	번역 텍스트에 사용하는 16진수 색상
`data[].blocks[].handwritten`	boolean	원문이 손글씨로 감지되었는지 여부
`data[].blocks[].location`	object	텍스트 블록의 네 모서리 경계
`data[].blocks[].location.left_bottom`	array<number>	해당 모서리의 좌표 쌍
`data[].blocks[].location.right_bottom`	array<number>	해당 모서리의 좌표 쌍
`data[].blocks[].location.left_top`	array<number>	해당 모서리의 좌표 쌍
`data[].blocks[].location.right_top`	array<number>	해당 모서리의 좌표 쌍
`data[].blocks[].text`	string	블록에 렌더링되는 번역 텍스트
`data[].blocks[].direction`	string	번역 텍스트의 쓰기 방향

필드	유형	설명
`subscription_credits`	integer	해당 범주의 크레딧 잔액
`subscription_credits_expires_at`	string \| null	구독 크레딧 만료 시간(ISO 8601 형식), 만료가 없으면 null
`one_time_credits`	integer	해당 범주의 크레딧 잔액
`one_time_credits_expires_at`	string \| null	일회성 크레딧 만료 시간(ISO 8601 형식), 만료가 없으면 null
`free_credits`	integer	해당 범주의 크레딧 잔액
`total_credits`	integer	사용 가능한 모든 크레딧 잔액의 합계
`is_temporary`	boolean	잔액이 임시 계정에 속하는지 여부

필드	유형	설명
`status`	integer	애플리케이션 상태 코드이며 성공 시 200
`cost_ms`	integer	이 API 요청을 처리하는 데 걸린 시간(밀리초)
`request_id`	string	이 API 호출을 추적하기 위한 요청 식별자
`data`	object	현재 크레딧 잔액을 담는 객체
`message`	string	성공한 API 응답에서는 항상 success이며 번역 작업 완료를 의미하지 않습니다
`data.total_credits`	integer	사용 가능한 모든 크레딧 잔액의 합계
`data.is_temporary`	boolean	잔액이 임시 계정에 속하는지 여부
`data.detail`	object	카테고리별 사용 가능 크레딧 내역
`data.detail.subscription`	object	해당 카테고리의 크레딧 잔액과 만료 시간
`data.detail.subscription.credits`	integer	해당 범주의 크레딧 잔액
`data.detail.subscription.expires_at`	string \| null	크레딧 만료 시간(ISO 8601 형식), 만료가 없으면 null
`data.detail.one_time`	object	해당 카테고리의 크레딧 잔액과 만료 시간
`data.detail.one_time.credits`	integer	해당 범주의 크레딧 잔액
`data.detail.one_time.expires_at`	string \| null	크레딧 만료 시간(ISO 8601 형식), 만료가 없으면 null
`data.detail.free`	object	해당 카테고리의 크레딧 잔액과 만료 시간
`data.detail.free.credits`	integer	해당 범주의 크레딧 잔액
`data.detail.free.expires_at`	null	현재 집계 API가 무료 크레딧의 단일 만료 시간을 제공하지 않으므로 항상 null

응답 예시(JSON)

{
  "task_id": "00000000-0000-4000-8000-000000000001",
  "batch_id": "00000000-0000-4000-8000-000000000001"
}

응답 예시(JSON)

{
  "status": 200,
  "cost_ms": 125,
  "request_id": "4b7370383cacccc7",
  "data": {
    "task_id": "00000000-0000-4000-8000-000000000001",
    "batch_id": "00000000-0000-4000-8000-000000000001"
  },
  "message": "success"
}

응답 예시(JSON)

{
  "status_code": 200,
  "request_id": "4b7370383cacccc7",
  "auth_type": "account",
  "task_reference": "00000000-0000-4000-8000-000000000001",
  "data": {
    "items": [
      {
        "image_id": "00000000-0000-4000-8000-000000000001_0",
        "index": 0,
        "filename": "007.jpg",
        "status": "completed",
        "original_url": "https://storage.example.com/manga-demo/input/00000000-0000-4000-8000-000000000001/007.jpg",
        "translated_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
        "is_translated": true,
        "output_file_path": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
        "message": "ok",
        "error": null,
        "inpaint_image_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007-erased.jpg",
        "block_json": []
      }
    ],
    "task_status": "completed"
  }
}

응답 예시(JSON)

{
  "status": 200,
  "cost_ms": 5300,
  "request_id": "4b7370383cacccc7",
  "data": [
    {
      "image_id": "00000000-0000-4000-8000-000000000001_0",
      "filename": "007.jpg",
      "status": "completed",
      "original_url": "https://storage.example.com/manga-demo/input/00000000-0000-4000-8000-000000000001/007.jpg",
      "translated_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
      "erased_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007-erased.jpg",
      "blocks": [
        {
          "angle": 0,
          "color": "#484848",
          "handwritten": false,
          "location": {
            "left_bottom": [1685, 293],
            "right_bottom": [1786, 293],
            "left_top": [1685, 264],
            "right_top": [1786, 264]
          },
          "text": "OOOUGH!",
          "direction": "horizontal"
        }
      ]
    }
  ],
  "message": "success"
}

응답 예시(JSON)

{
  "subscription_credits": 0,
  "subscription_credits_expires_at": null,
  "one_time_credits": 0,
  "one_time_credits_expires_at": null,
  "free_credits": 10,
  "total_credits": 10,
  "is_temporary": true
}

응답 예시(JSON)

{
  "status": 200,
  "cost_ms": 4,
  "request_id": "4b7370383cacccc7",
  "data": {
    "total_credits": 10,
    "is_temporary": true,
    "detail": {
      "subscription": {
        "credits": 0,
        "expires_at": null
      },
      "one_time": {
        "credits": 0,
        "expires_at": null
      },
      "free": {
        "credits": 10,
        "expires_at": null
      }
    }
  },
  "message": "success"
}

오류 응답 매개변수

V2 실패 시 HTTP 상태를 유지하고 동일한 5개 필드 엔벌로프를 반환합니다.

필드	유형	설명
`status`	integer	실제 HTTP 오류 상태 코드
`cost_ms`	integer	이 API 요청을 처리하는 데 걸린 시간(밀리초)
`request_id`	string	이 API 호출을 추적하기 위한 요청 식별자
`data`	object	안정적인 기계 판독 가능 코드만 포함하는 오류 데이터 컨테이너
`message`	string	공개 오류 메시지이며 내부 진단 세부 정보는 노출되지 않습니다
`data.code`	string	안정적인 기계 판독 가능 오류 코드

오류 응답 예시(JSON)

{
  "status": 400,
  "cost_ms": 1,
  "request_id": "4b7370383cacccc7",
  "data": {
    "code": "PZ_API_ACCESS_BAD_REQUEST"
  },
  "message": "Invalid target language"
}

예제 입력

API 키

원본 언어

대상 언어

모델

글꼴

API 예제

경로

매개변수

응답 매개변수

응답 예시(JSON)

응답 예시(JSON)

응답 예시(JSON)

응답 예시(JSON)

응답 예시(JSON)

응답 예시(JSON)

오류 응답 매개변수

오류 응답 예시(JSON)

예제 입력

Python3 예제

cURL 예제

Python3 예제

cURL

Python3 예제

cURL

경로

매개변수

응답 매개변수

응답 예시(JSON)

응답 예시(JSON)

응답 예시(JSON)

응답 예시(JSON)

응답 예시(JSON)

응답 예시(JSON)

오류 응답 매개변수

오류 응답 예시(JSON)

예제 입력

Python3 예제

cURL 예제

Python3 예제

cURL

Python3 예제

cURL

쿠키 환경설정