API 참조

Qwen Image Edit API 는 이미지 편집 및 분석 기능을 애플리케이션에 통합할 수 있는 강력한 인터페이스를 제공합니다. 이 문서는 사용 가능한 엔드포인트, 매개변수 및 응답에 대한 포괄적인 참조를 제공합니다.

1. 인증

모든 API 요청은 API 키를 사용하여 인증되어야 합니다. API 키는 요청 헤더에 Authorization: Bearer YOUR_API_KEY 형식으로 포함되어야 합니다.

GET /api/v1/edit/text HTTP/1.1
Host: api.qwenimageedit.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

2. 핵심 메서드

editText

이미지 내의 텍스트를 수정, 번역 또는 교정합니다.

• 엔드포인트: POST /api/v1/edit/text
• 요청 본문:
  • imageUrl (string, 필수): 편집할 이미지의 URL.
  • textToFind (string, 필수): 이미지에서 찾을 텍스트.
  • textToReplace (string, 선택 사항): textToFind 를 대체할 텍스트. targetLanguage 가 제공되면 무시됩니다.
  • targetLanguage (string, 선택 사항): textToFind 를 번역할 언어 코드 (예: 'en', 'ko', 'fr'). textToReplace 와 함께 사용할 수 없습니다.
• 응답:
  • editedImageUrl (string): 편집된 이미지의 URL.
  • jobId (string, 비동기 모드인 경우): 비동기 작업의 ID.

editElement

이미지에 요소를 추가, 제거 또는 수정합니다.

• 엔드포인트: POST /api/v1/edit/element
• 요청 본문:
  • imageUrl (string, 필수): 편집할 이미지의 URL.
  • elementType (string, 필수): 추가할 요소의 유형 (예: 'logo', 'watermark', 'priceTag', 'infoBox').
  • elementUrl (string, elementType 가 'logo' 또는 'banner' 인 경우 필수): 추가할 요소 이미지의 URL.
  • text (string, elementType 가 'watermark', 'priceTag', 'infoBox' 인 경우 필수): 요소에 표시할 텍스트.
  • position (object, 선택 사항): 요소의 위치 (x, y 픽셀).
  • scale (number, 선택 사항): 요소의 크기 조정 비율 (0.0 - 1.0).
  • opacity (number, 선택 사항): 요소의 불투명도 (0.0 - 1.0).
  • backgroundColor (string, 선택 사항): 요소의 배경색 (예: '#RRGGBB').
  • color (string, 선택 사항): 요소의 텍스트 색상 (예: '#RRGGBB').
• 응답:
  • editedImageUrl (string): 편집된 이미지의 URL.
  • jobId (string, 비동기 모드인 경우): 비동기 작업의 ID.

transferStyle

이미지에 다른 이미지의 스타일을 전송합니다.

• 엔드포인트: POST /api/v1/transfer/style
• 요청 본문:
  • imageUrl (string, 필수): 스타일을 적용할 이미지의 URL.
  • styleImageUrl (string, 필수): 스타일을 가져올 이미지의 URL.
  • strength (number, 선택 사항): 스타일 전송의 강도 (0.0 - 1.0, 기본값: 0.8).
• 응답:
  • styledImageUrl (string): 스타일이 적용된 이미지의 URL.
  • jobId (string, 비동기 모드인 경우): 비동기 작업의 ID.

analyzeImage

이미지 콘텐츠에 대한 심층 분석을 수행합니다.

• 엔드포인트: POST /api/v1/analyze/image
• 요청 본문:
  • imageUrl (string, 필수): 분석할 이미지의 URL.
  • features (array of string, 필수): 분석할 기능 목록 (예: 'text', 'objects', 'faces', 'colors', 'style', 'quality').
• 응답:
  • text (array of object, text 기능이 요청된 경우): 감지된 텍스트 및 해당 속성.
  • objects (array of string, objects 기능이 요청된 경우): 감지된 개체 목록.
  • faces (array of object, faces 기능이 요청된 경우): 감지된 얼굴 및 해당 속성.
  • colors (object, colors 기능이 요청된 경우): 이미지의 주요 색상 팔레트.
  • style (object, style 기능이 요청된 경우): 이미지의 예술적 스타일 특성.
  • quality (object, quality 기능이 요청된 경우): 이미지의 품질 지표.

3. 유틸리티 메서드

resizeImage

이미지의 크기를 조정합니다.

• 엔드포인트: POST /api/v1/util/resize
• 요청 본문:
  • imageUrl (string, 필수): 크기를 조정할 이미지의 URL.
  • width (number, 필수): 새 너비 (픽셀).
  • height (number, 필수): 새 높이 (픽셀).
  • fit (string, 선택 사항): 이미지 맞춤 모드 (예: 'cover', 'contain', 'fill', 'inside', 'outside').
• 응답:
  • resizedImageUrl (string): 크기가 조정된 이미지의 URL.

enhanceImage

이미지 품질을 향상시킵니다 (예: 노이즈 제거, 선명도 향상).

• 엔드포인트: POST /api/v1/util/enhance
• 요청 본문:
  • imageUrl (string, 필수): 향상시킬 이미지의 URL.
  • enhancementType (string, 선택 사항): 적용할 향상 유형 (예: 'denoise', 'sharpen', 'color_correct').
• 응답:
  • enhancedImageUrl (string): 향상된 이미지의 URL.

cleanImage

이미지에서 원치 않는 개체 또는 결함을 제거합니다.

• 엔드포인트: POST /api/v1/util/clean
• 요청 본문:
  • imageUrl (string, 필수): 정리할 이미지의 URL.
  • areasToClean (array of object, 필수): 정리할 영역의 좌표 및 크기 (x, y, width, height).
• 응답:
  • cleanedImageUrl (string): 정리된 이미지의 URL.

4. 고급 구성

API 요청에 추가 매개변수를 포함하여 동작을 사용자 정의할 수 있습니다.

• async (boolean): 요청을 비동기적으로 처리할지 여부 (기본값: false). true 로 설정하면 응답에 jobId 가 포함됩니다.
• webhookUrl (string): 비동기 작업 완료 시 알림을 받을 URL.
• callbackData (object): Webhook 알림에 포함될 사용자 정의 데이터.

5. 오류 처리

API 는 표준 HTTP 상태 코드를 사용하여 성공 또는 실패를 나타냅니다. 오류가 발생하면 응답 본문에 문제에 대한 자세한 정보가 포함됩니다.

• 200 OK: 요청 성공.
• 400 Bad Request: 잘못된 요청 매개변수.
• 401 Unauthorized: 유효하지 않거나 누락된 API 키.
• 403 Forbidden: API 키에 필요한 권한이 없습니다.
• 404 Not Found: 요청된 리소스가 없습니다.
• 429 Too Many Requests: 속도 제한 초과.
• 500 Internal Server Error: API 서버 오류.

오류 응답 예시:

{
  "code": "INVALID_API_KEY",
  "message": "The provided API key is invalid or expired."
}

6. 제한 및 할당량

API 사용에는 계정 유형에 따라 제한 및 할당량이 적용됩니다. 자세한 내용은 가격 책정 페이지를 참조하십시오.

7. Webhook

비동기 작업이 완료되면 Qwen Image Edit 는 구성된 webhookUrl 로 HTTP POST 요청을 보냅니다. 요청 본문에는 jobId, status (예: 'completed', 'failed'), result (성공 시) 및 error (실패 시) 가 포함됩니다.

{
  "jobId": "your-job-id",
  "status": "completed",
  "result": {
    "editedImageUrl": "https://example.com/edited-image.jpg"
  },
  "callbackData": {
    "originalRequestId": "abc-123"
  }
}

8. SDK

Qwen Image Edit 는 다음 언어에 대한 공식 SDK 를 제공하여 API 와의 상호 작용을 단순화합니다.

• JavaScript/TypeScript SDK
• Python SDK
• PHP SDK
• Java SDK
• Go SDK
• Ruby SDK

SDK 를 사용하면 HTTP 요청을 수동으로 구성할 필요 없이 API 를 쉽게 호출할 수 있습니다.