{
  "openapi": "3.1.0",
  "info": {
    "title": "크레딧 사용량 조회 API",
    "description": "생성된 이미지 품질, 기본값 `2K`\n\n**참고:**\n- `4K` 품질은 추가 요금이 발생합니다",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.evolink.ai",
      "description": "프로덕션 환경"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/credits": {
      "get": {
        "summary": "크레딧 사용량 조회",
        "description": "생성된 이미지 품질, 기본값 `2K`\n\n**참고:**\n- `4K` 품질은 추가 요금이 발생합니다",
        "operationId": "getCredits",
        "tags": [
          "계정 관리"
        ],
        "responses": {
          "200": {
            "description": "크레딧 정보가 성공적으로 조회되었습니다",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreditsResponse"
                },
                "example": {
                  "data": {
                    "token": {
                      "remaining_credits": 99416.4429,
                      "unlimited_credits": false,
                      "used_credits": 583.5571
                    },
                    "user": {
                      "remaining_credits": 1095.3996,
                      "used_credits": 135.9048
                    }
                  },
                  "message": "",
                  "success": true
                }
              }
            }
          },
          "400": {
            "description": "잘못된 요청 매개변수",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "code": 400,
                    "message": "잘못된 요청",
                    "type": "invalid_request_error"
                  }
                }
              }
            }
          },
          "401": {
            "description": "인증 실패, 유효하지 않거나 만료된 토큰",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "code": 401,
                    "message": "Invalid or expired token",
                    "type": "authentication_error"
                  }
                }
              }
            }
          },
          "403": {
            "description": "접근 거부",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "code": 403,
                    "message": "접근 거부",
                    "type": "permission_error"
                  }
                }
              }
            }
          },
          "429": {
            "description": "랜덤 시드, 범위 `[0, 2147483647]`, 동일한 시드 값을 사용하면 생성 결과를 일관되게 유지할 수 있습니다",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "code": 429,
                    "message": "랜덤 시드, 범위 `[0, 2147483647]`, 동일한 시드 값을 사용하면 생성 결과를 일관되게 유지할 수 있습니다",
                    "type": "rate_limit_error",
                    "fallback_suggestion": "retry after 60 seconds"
                  }
                }
              }
            }
          },
          "500": {
            "description": "내부 서버 오류",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "code": 500,
                    "message": "내부 서버 오류",
                    "type": "internal_server_error",
                    "fallback_suggestion": "try again later"
                  }
                }
              }
            }
          },
          "502": {
            "description": "업스트림 서비스 오류",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "code": 502,
                    "message": "업스트림 서비스 오류",
                    "type": "upstream_error",
                    "fallback_suggestion": "try again later"
                  }
                }
              }
            }
          },
          "503": {
            "description": "서비스 일시적으로 사용 불가",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "code": 503,
                    "message": "서비스 일시적으로 사용 불가",
                    "type": "service_unavailable_error",
                    "fallback_suggestion": "retry after 30 seconds"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CreditsResponse": {
        "type": "object",
        "required": [
          "data",
          "message",
          "success"
        ],
        "properties": {
          "data": {
            "type": "object",
            "required": [
              "token",
              "user"
            ],
            "properties": {
              "token": {
                "type": "object",
                "description": "토큰 크레딧 정보",
                "required": [
                  "remaining_credits",
                  "unlimited_credits",
                  "used_credits"
                ],
                "properties": {
                  "remaining_credits": {
                    "type": "number",
                    "format": "double",
                    "description": "토큰의 잔여 크레딧",
                    "example": 99416.4429
                  },
                  "unlimited_credits": {
                    "type": "boolean",
                    "description": "토큰의 무제한 크레딧 여부",
                    "example": false
                  },
                  "used_credits": {
                    "type": "number",
                    "format": "double",
                    "description": "토큰이 사용한 크레딧",
                    "example": 583.5571
                  }
                }
              },
              "user": {
                "type": "object",
                "description": "사용자 크레딧 정보",
                "required": [
                  "remaining_credits",
                  "used_credits"
                ],
                "properties": {
                  "remaining_credits": {
                    "type": "number",
                    "format": "double",
                    "description": "사용자의 잔여 크레딧",
                    "example": 1095.3996
                  },
                  "used_credits": {
                    "type": "number",
                    "format": "double",
                    "description": "사용자가 사용한 크레딧",
                    "example": 135.9048
                  }
                }
              }
            }
          },
          "message": {
            "type": "string",
            "description": "응답 메시지",
            "example": ""
          },
          "success": {
            "type": "boolean",
            "description": "요청 성공 여부",
            "example": true
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "integer",
                "description": "HTTP 상태 오류 코드",
                "example": 401
              },
              "message": {
                "type": "string",
                "description": "오류 설명",
                "example": "Invalid or expired token"
              },
              "type": {
                "type": "string",
                "description": "오류 유형",
                "example": "authentication_error"
              },
              "param": {
                "type": "string",
                "description": "관련 매개변수 이름",
                "example": "token"
              },
              "fallback_suggestion": {
                "type": "string",
                "description": "오류 처리 제안",
                "example": "retry after 60 seconds"
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "##모든 API는 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": "크레딧 조회 등을 포함한 계정 관련 API"
    }
  ]
}